

<!doctype html>

<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>RTG Command Reference &#8212; RTG Tools Operations Manual v3.12</title>
    <link rel="stylesheet" href="_static/bizstyle.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    
    <script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
    <script src="_static/jquery.js"></script>
    <script src="_static/underscore.js"></script>
    <script src="_static/doctools.js"></script>
    <script src="_static/language_data.js"></script>
    <script src="_static/bizstyle.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="RTG product usage - baseline progressions" href="product_usage.html" />
    <link rel="prev" title="Overview" href="overview.html" />
    <meta name="viewport" content="width=device-width,initial-scale=1.0">
    <!--[if lt IE 9]>
    <script src="_static/css3-mediaqueries.js"></script>
    <![endif]-->
  </head><body>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="product_usage.html" title="RTG product usage - baseline progressions"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="overview.html" title="Overview"
             accesskey="P">previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="index.html">RTG Tools Operations Manual v3.12</a> &#187;</li>
        <li class="nav-item nav-item-this"><a href="">RTG Command Reference</a></li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <div class="section" id="rtg-command-reference">
<h1>RTG Command Reference<a class="headerlink" href="#rtg-command-reference" title="Permalink to this headline">¶</a></h1>
<p>This chapter describes RTG commands with a generic description of
parameter options and usage. This section also includes expected
operation and output results.</p>
<div class="section" id="command-line-interface-cli">
<h2>Command line interface (CLI)<a class="headerlink" href="#command-line-interface-cli" title="Permalink to this headline">¶</a></h2>
<p>RTG is installed as a single executable in any system subdirectory where
permissions authorize a particular community of users to run the
application. RTG commands are executed through the RTG command-line
interface (CLI). Each command has its own set of parameters and options
described in this section. The availability of each command may be
determined by the RTG license that has been installed. Contact
<code class="docutils literal notranslate"><span class="pre">support&#64;realtimegenomics.com</span></code> to discuss changing the set of commands
that are enabled by your license.</p>
<p>Results are organized in results directories defined by command
parameters and settings. The command line shell environment should
include a set of familiar text post-processing tools, such as <code class="docutils literal notranslate"><span class="pre">grep</span></code>,
<code class="docutils literal notranslate"><span class="pre">awk</span></code>, or <code class="docutils literal notranslate"><span class="pre">perl</span></code>. Otherwise, no additional applications such as
databases or directory services are required.</p>
</div>
<div class="section" id="rtg-command-syntax">
<h2>RTG command syntax<a class="headerlink" href="#rtg-command-syntax" title="Permalink to this headline">¶</a></h2>
<p><strong>Usage:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>rtg COMMAND [OPTIONS] &lt;REQUIRED&gt;
</pre></div>
</div>
<p>To run an RTG command at the command prompt (either DOS window or Unix
terminal), type the product name followed by the command and all
required and optional parameters. For example:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg format -o human_REF_SDF human_REF.fasta
</pre></div>
</div>
<p>Typically results are written to output files specified with the <code class="docutils literal notranslate"><span class="pre">-o</span></code>
option. There is no default filename or filename extension added to
commands requiring specification of an output directory or format.</p>
<p>Many times, unfiltered output files are very large; the built-in
compression option generates block compressed output files with the
.<code class="docutils literal notranslate"><span class="pre">gz</span></code> extension automatically unless the parameter <code class="docutils literal notranslate"><span class="pre">-Z</span></code> or <code class="docutils literal notranslate"><span class="pre">--no-gzip</span></code>
is issued with the command.</p>
<p>Many command parameters require user-supplied information of various
types, as shown in the following:</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 17%" />
<col style="width: 83%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Type</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>DIR, FILE</p></td>
<td><p>File or directory name(s)</p></td>
</tr>
<tr class="row-odd"><td><p>SDF</p></td>
<td><p>Sequence data that has been formatted to SDF</p></td>
</tr>
<tr class="row-even"><td><p>INT</p></td>
<td><p>Integer value</p></td>
</tr>
<tr class="row-odd"><td><p>FLOAT</p></td>
<td><p>Floating point decimal value</p></td>
</tr>
<tr class="row-even"><td><p>STRING</p></td>
<td><p>A sequence of characters for comments, filenames, or labels</p></td>
</tr>
<tr class="row-odd"><td><p>REGION</p></td>
<td><p>A genomic region specification (see below)</p></td>
</tr>
</tbody>
</table>
<p>Genomic region parameters take one of the following forms:</p>
<ul class="simple">
<li><p>sequence_name (e.g.: <code class="docutils literal notranslate"><span class="pre">chr21</span></code>) corresponds to the entirety of the
named sequence.</p></li>
<li><p>sequence_name:start (e.g.: <code class="docutils literal notranslate"><span class="pre">chr21:100000</span></code>) corresponds to a single
position on the named sequence.</p></li>
<li><p>sequence_name:start-end (e.g.: <code class="docutils literal notranslate"><span class="pre">chr21:100000-110000</span></code>) corresponds to a
range that extends from the specified start position to the specified
end position (inclusive). The positions are 1-based.</p></li>
<li><p>sequence_name:position+length (e.g.: <code class="docutils literal notranslate"><span class="pre">chr21:100000+10000</span></code>) corresponds
to a range that extends from the specified start position that
includes the specified number of nucleotides.</p></li>
<li><p>sequence_name:position~padding (e.g.: <code class="docutils literal notranslate"><span class="pre">chr21:100000~10000</span></code>)
corresponds to a range that spans the specified position by the
specified amount of padding on either side.</p></li>
</ul>
<p>To display all parameters and syntax associated with an RTG command,
enter the command and type <code class="docutils literal notranslate"><span class="pre">--help</span></code>. For example: all parameters
available for the RTG <code class="docutils literal notranslate"><span class="pre">format</span></code> command are displayed when <code class="docutils literal notranslate"><span class="pre">rtg</span> <span class="pre">format</span>
<span class="pre">--help</span></code> is executed, the output of which is shown below.</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Usage: rtg format [OPTION]... -o SDF FILE+
                  [OPTION]... -o SDF -I FILE
                  [OPTION]... -o SDF -l FILE -r FILE

Converts the contents of sequence data files (FASTA/FASTQ/SAM/BAM) into the RTG
Sequence Data File (SDF) format.

File Input/Output
  -f, --format=FORMAT            format of input. Allowed values are [fasta,
                                 fastq, sam-se, sam-pe, cg-fastq, cg-sam]
                                 (Default is fasta)
  -I, --input-list-file=FILE     file containing a list of input read files (1
                                 per line)
  -l, --left=FILE                left input file for FASTA/FASTQ paired end
                                 data
  -o, --output=SDF               name of output SDF
  -p, --protein                  input is protein. If this option is not
                                 specified, then the input is assumed to
                                 consist of nucleotides
  -q, --quality-format=FORMAT    format of quality data for fastq files (use
                                 sanger for Illumina 1.8+). Allowed values are
                                 [sanger, solexa, illumina]
  -r, --right=FILE               right input file for FASTA/FASTQ paired end
                                 data
      FILE+                      input sequence files. May be specified 0 or
                                 more times

Filtering
      --duster                   treat lower case residues as unknowns
      --exclude=STRING           exclude input sequences based on their name.
                                 If the input sequence contains the specified
                                 string then that sequence is excluded from the
                                 SDF. May be specified 0 or more times
      --select-read-group=STRING when formatting from SAM/BAM input, only
                                 include reads with this read group ID
      --trim-threshold=INT       trim read ends to maximise base quality above
                                 the given threshold

Utility
      --allow-duplicate-names    disable checking for duplicate sequence names
  -h, --help                     print help on command-line flag usage
      --no-names                 do not include name data in the SDF output
      --no-quality               do not include quality data in the SDF output
      --sam-rg=STRING|FILE       file containing a single valid read group SAM
                                 header line or a string in the form
                                 &quot;@RG\tID:READGROUP1\tSM:BACT_SAMPLE\tPL:ILLUMINA&quot;
</pre></div>
</div>
<p>Required parameters are indicated in the usage display; optional
parameters are listed immediately below the usage information in
organized categories.</p>
<p>Use the double-dash when typing the full-word command option, as in
<code class="docutils literal notranslate"><span class="pre">--output</span></code>:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg format --output human_REF_SDF human_REF.fasta
</pre></div>
</div>
<p>Commonly used command options provide an abbreviated single-character
version of a full command parameter, indicated with only a single dash,
(Thus <code class="docutils literal notranslate"><span class="pre">--output</span></code> is the same as specifying the command option with the
abbreviated character <code class="docutils literal notranslate"><span class="pre">-o</span></code>):</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg format -o human_REF human_REF.fasta
</pre></div>
</div>
<p>A set of utility commands are provided through the CLI: <code class="docutils literal notranslate"><span class="pre">version</span></code>,
<code class="docutils literal notranslate"><span class="pre">license</span></code>, and <code class="docutils literal notranslate"><span class="pre">help</span></code>. Start with these commands to familiarize yourself
with the software.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">rtg</span> <span class="pre">version</span></code> command invokes the RTG software and triggers the
launch of RTG product commands, options, and utilities:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg version
</pre></div>
</div>
<p>It will display the version of the RTG software installed, RAM
requirements, and license expiration, for example:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$rtg version
Product: RTG Core 3.5
Core Version: 6236f4e (2014-10-31)
RAM: 40.0GB of 47.0GB RAM can be used by rtg (84%)
License: Expires on 2015-09-30
License location: /home/rtgcustomer/rtg/rtg-license.txt
Contact: support@realtimegenomics.com

Patents / Patents pending:
US: 7,640,256, 13/129,329, 13/681,046, 13/681,215, 13/848,653,
13/925,704, 14/015,295, 13/971,654, 13/971,630, 14/564,810
UK: 1222923.3, 1222921.7, 1304502.6, 1311209.9, 1314888.7, 1314908.3
New Zealand: 626777, 626783, 615491, 614897, 614560
Australia: 2005255348, Singapore: 128254

Citation:
John G. Cleary, Ross Braithwaite, Kurt Gaastra, Brian S. Hilbush, Stuart
Inglis, Sean A. Irvine, Alan Jackson, Richard Littin, Sahar
Nohzadeh-Malakshah, Mehul Rathod, David Ware, Len Trigg, and Francisco
M. De La Vega. &quot;Joint Variant and De Novo Mutation Identification on
Pedigrees from High-Throughput Sequencing Data.&quot; Journal of
Computational Biology. June 2014, 21(6): 405-419.
doi:10.1089/cmb.2014.0029.
(c) Real Time Genomics Inc, 2014
</pre></div>
</div>
<p>To see what commands you are licensed to use, type <code class="docutils literal notranslate"><span class="pre">rtg</span> <span class="pre">license</span></code>:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$rtg license
License: Expires on 2015-03-30
Licensed to: John Doe
License location: /home/rtgcustomer/rtg/rtg-license.txt

    Command name    Licensed?  Release Level

Data formatting:
    format          Licensed   GA
    sdf2fasta       Licensed   GA
    sdf2fastq       Licensed   GA

Utility:
    bgzip           Licensed   GA
    index           Licensed   GA
    extract         Licensed   GA
    sdfstats        Licensed   GA
    sdfsubset       Licensed   GA
    sdfsubseq       Licensed   GA
    mendelian       Licensed   GA
    vcfstats        Licensed   GA
    vcfmerge        Licensed   GA
    vcffilter       Licensed   GA
    vcfannotate     Licensed   GA
    vcfsubset       Licensed   GA
    vcfeval         Licensed   GA
    pedfilter       Licensed   GA
    pedstats        Licensed   GA
    rocplot         Licensed   GA
    version         Licensed   GA
    license         Licensed   GA
    help            Licensed   GA
</pre></div>
</div>
<p>To display all commands and usage parameters available to use with your
license, type <code class="docutils literal notranslate"><span class="pre">rtg</span> <span class="pre">help</span></code>:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg help
Usage: rtg COMMAND [OPTION]...
       rtg RTG_MEM=16G COMMAND [OPTION]...  (e.g. to set maximum memory use to 16 GB)

Type ``rtg help COMMAND`` for help on a specific command. The
following commands are available:

Data formatting:
      format                 convert a FASTA file to SDF
      cg2sdf                 convert Complete Genomics reads to SDF
      sdf2fasta              convert SDF to FASTA
      sdf2fastq              convert SDF to FASTQ
      sdf2sam                convert SDF to SAM/BAM
Read mapping:
      map                    read mapping
      mapf                   read mapping for filtering purposes
      cgmap                  read mapping for Complete Genomics data
Protein search:
      mapx                   translated protein search
Assembly:
      assemble               assemble reads into long sequences
      addpacbio              add Pacific Biosciences reads to an assembly
Variant detection:
      calibrate              create calibration data from SAM/BAM files
      svprep                 prepare SAM/BAM files for sv analysis
      sv                     find structural variants
      discord                detect structural variant breakends using discordant reads
      coverage               calculate depth of coverage from SAM/BAM files
      snp                    call variants from SAM/BAM files
      family                 call variants for a family following Mendelian inheritance
      somatic                call variants for a tumor/normal pair
      population             call variants for multiple potentially-related individuals
      lineage                call de novo variants in a cell lineage
      avrbuild               AVR model builder
      avrpredict             run AVR on a VCF file
      cnv                    call CNVs from paired SAM/BAM files
Metagenomics:
      species                estimate species frequency in metagenomic samples
      similarity             calculate similarity matrix and nearest neighbor tree
Simulation:
      genomesim              generate simulated genome sequence
      cgsim                  generate simulated reads from a sequence
      readsim                generate simulated reads from a sequence
      readsimeval            evaluate accuracy of mapping simulated reads
      popsim                 generate a VCF containing simulated population variants
      samplesim              generate a VCF containing a genotype simulated from a population
      childsim               generate a VCF containing a genotype simulated as a child of two parents
      denovosim              generate a VCF containing a derived genotype containing de novo variants
      samplereplay           generate the genome corresponding to a sample genotype
      cnvsim                 generate a mutated genome by adding CNVs to a template
Utility:
      bgzip                  compress a file using block gzip
      index                  create a tabix index
      extract                extract data from a tabix indexed file
      sdfstats               print statistics about an SDF
      sdfsplit               split an SDF into multiple parts
      sdfsubset              extract a subset of an SDF into a new SDF
      sdfsubseq              extract a subsequence from an SDF as text
      sam2bam                convert SAM file to BAM file and create index
      sammerge               merge sorted SAM/BAM files
      samstats               print statistics about a SAM/BAM file
      samrename              rename read id to read name in SAM/BAM files
      mapxrename             rename read id to read name in mapx output files
      mendelian              check a multi-sample VCF for Mendelian consistency
      vcfstats               print statistics from about variants contained within a VCF file
      vcfmerge               merge single-sample VCF files into a single multi-sample VCF
      vcffilter              filter records within a VCF file
      vcfannotate            annotate variants within a VCF file
      vcfsubset              create a VCF file containing a subset of the original columns
      vcfeval                evaluate called variants for agreement with a baseline variant set
      pedfilter              filter and convert a pedigree file
      pedstats               print information about a pedigree file
      avrstats               print statistics about an AVR model
      rocplot                plot ROC curves from vcfeval ROC data files
      usageserver            run a local server for collecting RTG command usage information
      version                print version and license information
      license                print license information for all commands
      help                   print this screen or help for specified command
</pre></div>
</div>
<p>The help command will only list the commands for which you have a
license to use.</p>
<p>To display help and syntax information for a specific command from the
command line, type the command and then the –help option, as in:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg format --help
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The following commands are synonymous:
<code class="docutils literal notranslate"><span class="pre">rtg</span> <span class="pre">help</span> <span class="pre">format</span></code> and <code class="docutils literal notranslate"><span class="pre">rtg</span> <span class="pre">format</span> <span class="pre">--help</span></code></p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p>Refer to <a class="reference internal" href="overview.html#installation-and-deployment"><span class="std std-ref">Installation and deployment</span></a> for information
about installing the RTG product executable.</p>
</div>
</div>
<div class="section" id="data-formatting-commands">
<h2>Data Formatting Commands<a class="headerlink" href="#data-formatting-commands" title="Permalink to this headline">¶</a></h2>
<div class="section" id="format">
<h3>format<a class="headerlink" href="#format" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>The <code class="docutils literal notranslate"><span class="pre">format</span></code> command converts the contents of sequence data files
(FASTA/FASTQ/SAM/BAM) into the RTG Sequence Data File (SDF) format. This
step ensures efficient processing of very large data sets, by organizing
the data into multiple binary files within a named directory. The same
SDF format is used for storing sequence data, whether it be genomic
reference, sequencing reads, protein sequences, etc.</p>
<p><strong>Syntax:</strong></p>
<p>Format one or more files specified from command line into a single SDF:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg format [OPTION] -o SDF FILE+
</pre></div>
</div>
<p>Format one or more files specified in a text file into a single SDF:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg format [OPTION] -o SDF -I FILE
</pre></div>
</div>
<p>Format mate pair reads into a single SDF:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg format [OPTION] -o SDF -l FILE -r FILE
</pre></div>
</div>
<p><strong>Examples:</strong></p>
<p>For FASTA (<code class="docutils literal notranslate"><span class="pre">.fa</span></code>) genome reference data:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg format -o maize_reference maize_chr*.fa
</pre></div>
</div>
<p>For FASTQ (<code class="docutils literal notranslate"><span class="pre">.fq</span></code>) sequence read data:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg format -f fastq -q sanger -o h1_reads -l h1_sample_left.fq -r h1_sample_right.fq
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<table class="docutils align-default">
<colgroup>
<col style="width: 6%" />
<col style="width: 18%" />
<col style="width: 77%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>File Input/Output</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-f</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--format=FORMAT</span></code></p></td>
<td><p>The format of the input file(s). Allowed values are [fasta, fastq, fastq-interleaved, sam-se, sam-pe] (Default is fasta).</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-I</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--input-list-file=FILE</span></code></p></td>
<td><p>Specifies a file containing a list of sequence data files (one per line) to be converted into an SDF.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-l</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--left=FILE</span></code></p></td>
<td><p>The left input file for FASTA/FASTQ paired end data.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-o</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--output=SDF</span></code></p></td>
<td><p>The name of the output SDF.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-p</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--protein</span></code></p></td>
<td><p>Set if the input consists of protein. If this option is not specified, then the input is assumed to consist of nucleotides.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-q</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--quality-format=FORMAT</span></code></p></td>
<td><p>The format of the quality data for fastq format files. (Use sanger for Illumina1.8+). Allowed values are [sanger, solexa, illumina].</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-r</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--right=FILE</span></code></p></td>
<td><p>The right input file for FASTA/FASTQ paired end data.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">FILE+</span></code></p></td>
<td><p>Specifies a sequence data file to be converted into an SDF. May be specified 0 or more times.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 2%" />
<col style="width: 18%" />
<col style="width: 80%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Filtering</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--duster</span></code></p></td>
<td><p>Treat lower case residues as unknowns.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--exclude=STRING</span></code></p></td>
<td><p>Exclude individual input sequences based on their name. If the input sequence name contains the specified string then that sequence is excluded from the
SDF. May be specified 0 or more times.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--select-read-group=STRING</span></code></p></td>
<td><p>Set to only include only reads with this read group ID when formatting from SAM/BAM files.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--trim-threshold=INT</span></code></p></td>
<td><p>Set to trim the read ends to maximise the base quality above the given threshold.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 5%" />
<col style="width: 16%" />
<col style="width: 79%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Utility</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--allow-duplicate-names</span></code></p></td>
<td><p>Set to disable duplicate name detection.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-h</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--help</span></code></p></td>
<td><p>Prints help on command-line flag usage.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-names</span></code></p></td>
<td><p>Do not include sequence names in the resulting SDF.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-quality</span></code></p></td>
<td><p>Do not include sequence quality data in the resulting SDF.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--sam-rg=STRING|FILE</span></code></p></td>
<td><p>Specifies a file containing a single valid read group SAM header line or a string in the form <code class="docutils literal notranslate"><span class="pre">&#64;RG\tID:RG1\tSM:G1_SAMP\tPL:ILLUMINA</span></code>.</p></td>
</tr>
</tbody>
</table>
<p><strong>Usage:</strong></p>
<p>Formatting takes one or more input data files and creates a single SDF.
Specify the type of file to be converted, or allow default to FASTA
format. To aggregate multiple input data files, such as when formatting
a reference genome consisting of multiple chromosomes, list all files on
the command line or use the <code class="docutils literal notranslate"><span class="pre">--input-list-file</span></code> flag to specify a file
containing the list of files to process.</p>
<p>For input FASTA and FASTQ files which are compressed, they must have a
filename extension of <code class="docutils literal notranslate"><span class="pre">.gz</span></code> (for gzip compressed data) or <code class="docutils literal notranslate"><span class="pre">.bz2</span></code> (for
bzip2 compressed data).</p>
<p>When formatting human reference genome data, it is recommended that the
resulting SDF be augmented with chromosome reference metadata, in order
to enable automatic sex-aware features during mapping and variant
calling. The <code class="docutils literal notranslate"><span class="pre">format</span></code> command will automatically recognize several
common human reference genomes and install a reference configuration
file. If your reference genome is not recognized, a configuration can be
manually adapted from one of the examples provided in the RTG
distribution and installed in the SDF directory. The reference
configuration is described in <a class="reference internal" href="appendix.html#rtg-reference-file-format"><span class="std std-ref">RTG reference file format</span></a>.</p>
<p>When using FASTQ input files you must specify the quality format being
used as one of <code class="docutils literal notranslate"><span class="pre">sanger</span></code>, <code class="docutils literal notranslate"><span class="pre">solexa</span></code> or <code class="docutils literal notranslate"><span class="pre">illumina</span></code>. As of Illumina pipeline
version 1.8 and higher, quality values are encoded in Sanger format and
so should be formatted using <code class="docutils literal notranslate"><span class="pre">--quality-format=sanger</span></code>. Output from
earlier Illumina pipeline versions should be formatted using
<code class="docutils literal notranslate"><span class="pre">--quality-format=illumina</span></code> for Illumina pipeline versions starting with
1.3 and before 1.8, or <code class="docutils literal notranslate"><span class="pre">--quality-format=solexa</span></code> for Illumina pipeline
versions less than 1.3.</p>
<p>For FASTQ files that represent paired-end read data, indicate each side
respectively using the <code class="docutils literal notranslate"><span class="pre">--left=FILE</span></code> and <code class="docutils literal notranslate"><span class="pre">--right=FILE</span></code> flags.
Sometimes paired-end reads are represented in a single FASTQ file by
interleaving each side of the read.  This type of input can be
formatted by specifying <code class="docutils literal notranslate"><span class="pre">fastq-interleaved</span></code> as the format type.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">mapx</span></code> command maps translated DNA sequence data against a protein
reference. You must use the <code class="docutils literal notranslate"><span class="pre">-p</span></code>, <code class="docutils literal notranslate"><span class="pre">--protein</span></code> flag to format the protein
reference used by <code class="docutils literal notranslate"><span class="pre">mapx</span></code>.</p>
<p>Use the <code class="docutils literal notranslate"><span class="pre">sam-se</span></code> format for single end SAM/BAM input files and the
<code class="docutils literal notranslate"><span class="pre">sam-pe</span></code> format for paired end SAM/BAM input files. Note that if the
input SAM/BAM files are sorted in coordinate order (for example if they
have already been aligned to a reference), it is recommended that they
be shuffled before formatting, so that subsequent mapping is not biased
by processing reads in chromosome order. For example, a BAM file can be
shuffled using <code class="docutils literal notranslate"><span class="pre">samtools</span> <span class="pre">collate</span></code> as follows:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ samtools collate -uOn 256 reads.bam tmp-prefix &gt;reads_shuffled.bam
</pre></div>
</div>
<p>And this can be carried out on the fly during formatting using bash
process redirection in order to reduce intermediate I/O, for example:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg format --format sam-pe &lt;(samtools collate -uOn 256 reads.bam temp-prefix) ...
</pre></div>
</div>
<p>The SDF for a read set can contain a SAM read group which will be
automatically picked up from the input SAM/BAM files if they contain
only one read group. If the input SAM/BAM files contain multiple read
groups you must select a single read group from the SAM/BAM file to
format using the <code class="docutils literal notranslate"><span class="pre">--select-read-group</span></code> flag or specify a custom read
group with the <code class="docutils literal notranslate"><span class="pre">--sam-rg</span></code> flag. The <code class="docutils literal notranslate"><span class="pre">--sam-rg</span></code> flag can also be used to
add read group information to reads given in other input formats. The
SAM read group stored in an SDF will be automatically used during
mapping the reads it contains to provide tracking information in the
output BAM files.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">--trim-threshold</span></code> flag can be used to trim poor quality read ends
from the input reads by inspecting base qualities from FASTQ input. If
and only if the quality of the final base of the read is less than the
threshold given, a new read length is found which maximizes the overall
quality of the retained bases using the following formula.</p>
<div class="math">
<p><img src="_images/math/6c754ae3fc49dc56e236eb95ef00cfdcad3df594.png" alt="\arg \max x\left({\sum_{i=x+1}^l (T - q(i))}\right) \text{ if } q(l) &lt; T"/></p>
</div><p>Where <em>l</em> is the original read length, <em>x</em> is the new read length, <em>T</em>
is the given threshold quality and <em>q(n)</em> is the quality of the base at
the position n of the read.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Sequencing system read files and reference genome files
often have the same extension and it may not always be obvious which
file is a read set and which is a genome. Before formatting a sequencing
system file, open it to see which type of file it is. For example:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ less pf3.fa
</pre></div>
</div>
</div>
<p>In general, a read file typically begins with an <code class="docutils literal notranslate"><span class="pre">&#64;</span></code> or <code class="docutils literal notranslate"><span class="pre">+</span></code> character; a
genome reference file typically begins with the characters <code class="docutils literal notranslate"><span class="pre">chr</span></code>.</p>
<p>Normally when the input data contains multiple sequences with the same name the
format command will fail with an error. The <code class="docutils literal notranslate"><span class="pre">--allow-duplicate-names</span></code> flag
will disable this check conserving memory, but if the input data has multiple
sequences with the same name you will not be warned. Having duplicate sequence
names can cause problems with other commands, especially for reference data
since the output many commands identifies sequences by their names.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#sdf2fasta"><span class="std std-ref">sdf2fasta</span></a>,
<a class="reference internal" href="#sdf2fastq"><span class="std std-ref">sdf2fastq</span></a>,
<a class="reference internal" href="#sdfstats"><span class="std std-ref">sdfstats</span></a></p>
</div>
</div>
<div class="section" id="sdf2fasta">
<h3>sdf2fasta<a class="headerlink" href="#sdf2fasta" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>Convert SDF data into a FASTA file.</p>
<p><strong>Syntax:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg sdf2fasta [OPTION]... -i SDF -o FILE
</pre></div>
</div>
<p><strong>Example:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg sdf2fasta -i humanSDF -o humanFASTA_return
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<table class="docutils align-default">
<colgroup>
<col style="width: 7%" />
<col style="width: 19%" />
<col style="width: 74%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>File Input/Output</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-i</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--input=SDF</span></code></p></td>
<td><p>SDF containing sequences.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-o</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--output=FILE</span></code></p></td>
<td><p>Output filename (extension added if not present). Use ‘-‘ to write to standard output.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 6%" />
<col style="width: 12%" />
<col style="width: 82%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Filtering</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--end-id=INT</span></code></p></td>
<td><p>Only output sequences with sequence id less than the given number. (Sequence ids start at 0).</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--start-id=INT</span></code></p></td>
<td><p>Only output sequences with sequence id greater than or equal to the given number. (Sequence ids start at 0).</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-I</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--id-file=FILE</span></code></p></td>
<td><p>Name of a file containing a list of sequences to extract, one per line.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--names</span></code></p></td>
<td><p>Interpret any specified sequence as names instead of numeric sequence ids.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--taxons</span></code></p></td>
<td><p>Interpret any specified sequence as taxon ids instead of numeric sequence ids. This option only applies to a metagenomic reference species SDF.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">STRING+</span></code></p></td>
<td><p>Specify one or more explicit sequences to extract, as sequence id, or sequence name if –names flag is set.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 5%" />
<col style="width: 13%" />
<col style="width: 82%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Utility</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-h</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--help</span></code></p></td>
<td><p>Prints help on command-line flag usage.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--interleave</span></code></p></td>
<td><p>Interleave paired data into a single output file. Default is to split to separate output files.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-l</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--line-length=INT</span></code></p></td>
<td><p>Set the maximum number of nucleotides or amino acids to print on a line of FASTA output. Should be nonnegative, with a value of 0 indicating that the line
length is not capped. (Default is 0).</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-Z</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-gzip</span></code></p></td>
<td><p>Set this flag to create the FASTA output file without compression. By default the output file is compressed with blocked gzip.</p></td>
</tr>
</tbody>
</table>
<p><strong>Usage:</strong></p>
<p>Use the <code class="docutils literal notranslate"><span class="pre">sdf2fasta</span></code> command to convert SDF data into FASTA format. By
default, <code class="docutils literal notranslate"><span class="pre">sdf2fasta</span></code> creates a separate line of FASTA output for each
sequence. These lines will be as long as the sequences themselves. To
make them more readable, use the <code class="docutils literal notranslate"><span class="pre">-l</span></code>, <code class="docutils literal notranslate"><span class="pre">--line-length</span></code> flag and define a
reasonable record length like 75.</p>
<p>By default all sequences will be extracted, but flags may be specified
to extract reads within a range, or explicitly specified reads (either
by numeric sequence id or by sequence name if <code class="docutils literal notranslate"><span class="pre">--names</span></code> is set).
Additionally, when the input SDF is a metagenomic species reference SDF,
the <code class="docutils literal notranslate"><span class="pre">--taxons</span></code> option, any supplied id is interpreted as a taxon id and
all sequences assigned directly to that taxon id will be output. This
provides a convenient way to extract all sequence data corresponding to
a single (or multiple) species from a metagenomic species reference SDF.</p>
<p>Sequence ids are numbered starting at 0, the <code class="docutils literal notranslate"><span class="pre">--start-id</span></code> flag is an inclusive
lower bound on id and the <code class="docutils literal notranslate"><span class="pre">--end-id</span></code> flag is an exclusive upper bound. For
example if you have an SDF with five sequences (ids: 0, 1, 2, 3, 4) the
following command:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg sdf2fasta --start-id=3 -i mySDF -o output
</pre></div>
</div>
<p>will extract sequences with id 3 and 4. The command:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg sdf2fasta --end-id=3 -i mySDF -o output
</pre></div>
</div>
<p>will extract sequences with id 0, 1, and 2. And the command:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg sdf2fasta --start-id=2 --end-id=4 -i mySDF -o output
</pre></div>
</div>
<p>will extract sequences with id 2 and 3.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#format"><span class="std std-ref">format</span></a>,
<a class="reference internal" href="#sdf2fastq"><span class="std std-ref">sdf2fastq</span></a>,
<a class="reference internal" href="#sdfstats"><span class="std std-ref">sdfstats</span></a></p>
</div>
</div>
<div class="section" id="sdf2fastq">
<h3>sdf2fastq<a class="headerlink" href="#sdf2fastq" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>Convert SDF data into a FASTQ file.</p>
<p><strong>Syntax:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg sdf2fastq [OPTION]... -i SDF -o FILE
</pre></div>
</div>
<p><strong>Example:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg sdf2fastq -i humanSDF -o humanFASTQ_return
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<table class="docutils align-default">
<colgroup>
<col style="width: 10%" />
<col style="width: 21%" />
<col style="width: 69%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>File Input/Output</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-i</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--input=SDF</span></code></p></td>
<td><p>Specifies the SDF data to be converted.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-o</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--output=FILE</span></code></p></td>
<td><p>Specifies the file name used to write the resulting FASTQ output.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 7%" />
<col style="width: 15%" />
<col style="width: 78%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Filtering</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--end-id=INT</span></code></p></td>
<td><p>Only output sequences with sequence id less than the given number. (Sequence ids start at 0).</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--start-id=INT</span></code></p></td>
<td><p>Only output sequences with sequence id greater than or equal to the given number. (Sequence ids start at 0).</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-I</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--id-file=FILE</span></code></p></td>
<td><p>Name of a file containing a list of sequences to extract, one per line.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--names</span></code></p></td>
<td><p>Interpret any specified sequence as names instead of numeric sequence ids.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">STRING+</span></code></p></td>
<td><p>Specify one or more explicit sequences to extract, as sequence id, or sequence name if –names flag is set.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 5%" />
<col style="width: 14%" />
<col style="width: 80%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Utility</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-h</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--help</span></code></p></td>
<td><p>Prints help on command-line flag usage.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-q</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--default-qualty=INT</span></code></p></td>
<td><p>Set the default quality to use if the SDF does not contain sequence quality data (0-63).</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--interleave</span></code></p></td>
<td><p>Interleave paired data into a single output file. Default is to split to separate output files.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-l</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--line-length=INT</span></code></p></td>
<td><p>Set the maximum number of nucleotides or amino acids to print on a line of FASTQ output. Should be nonnegative, with a value of 0 indicating that the line
length is not capped. (Default is 0).</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-Z</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-gzip</span></code></p></td>
<td><p>Set this flag to create the FASTQ output file without compression. By default the output file is compressed with blocked gzip.</p></td>
</tr>
</tbody>
</table>
<p><strong>Usage:</strong></p>
<p>Use the <code class="docutils literal notranslate"><span class="pre">sdf2fastq</span></code> command to convert SDF data into FASTQ format. If no
quality data is available in the SDF, use the <code class="docutils literal notranslate"><span class="pre">-q</span></code>, <code class="docutils literal notranslate"><span class="pre">--default-quality</span></code>
flag to set a quality score for the FASTQ output. The quality encoding
used during output is sanger quality encoding. By default, <code class="docutils literal notranslate"><span class="pre">sdf2fastq</span></code>
creates a separate line of FASTQ output for each sequence. As with
<code class="docutils literal notranslate"><span class="pre">sdf2fasta</span></code>, there is an option to use the <code class="docutils literal notranslate"><span class="pre">-l</span></code>, <code class="docutils literal notranslate"><span class="pre">--line-length</span></code> flag to
restrict the line lengths to improve readability of long sequences.</p>
<p>By default all sequences will be extracted, but flags may be specified
to extract reads within a range, or explicitly specified reads (either
by numeric sequence id or by sequence name if <code class="docutils literal notranslate"><span class="pre">--names</span></code> is set).</p>
<p>It may be preferable to extract data to unaligned SAM/BAM format using
<code class="docutils literal notranslate"><span class="pre">sdf2sam</span></code>, as this preserves read-group information stored in the SDF
and may also be more convenient when dealing with paired-end data.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">--start-id</span></code> and <code class="docutils literal notranslate"><span class="pre">--end-id</span></code> flags behave as in <code class="docutils literal notranslate"><span class="pre">sdf2fasta</span></code>.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#format"><span class="std std-ref">format</span></a>,
<a class="reference internal" href="#sdf2fasta"><span class="std std-ref">sdf2fasta</span></a>,
<a class="reference internal" href="#sdf2sam"><span class="std std-ref">sdf2sam</span></a>,
<a class="reference internal" href="#sdfstats"><span class="std std-ref">sdfstats</span></a></p>
</div>
</div>
<div class="section" id="sdf2sam">
<h3>sdf2sam<a class="headerlink" href="#sdf2sam" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>Convert SDF read data into unaligned SAM or BAM format file.</p>
<p><strong>Syntax:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg sdf2sam [OPTION]... -i SDF -o FILE
</pre></div>
</div>
<p><strong>Example:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg sdf2sam -i samplereadsSDF -o samplereads.bam
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<table class="docutils align-default">
<colgroup>
<col style="width: 6%" />
<col style="width: 13%" />
<col style="width: 80%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>File Input/Output</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-i</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--input=SDF</span></code></p></td>
<td><p>Specifies the SDF data to be converted.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-o</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--output=FILE</span></code></p></td>
<td><p>Specifies the file name used to write the resulting SAM/BAM to. The output format is automatically determined based on the
filename specified. If ‘-‘ is given, the data is written as uncompressed SAM to standard output.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 7%" />
<col style="width: 15%" />
<col style="width: 78%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Filtering</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--end-id=INT</span></code></p></td>
<td><p>Only output sequences with sequence id less than the given number. (Sequence ids start at 0).</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--start-id=INT</span></code></p></td>
<td><p>Only output sequences with sequence id greater than or equal to the given number. (Sequence ids start at 0).</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-I</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--id-file=FILE</span></code></p></td>
<td><p>Name of a file containing a list of sequences to extract, one per line.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--names</span></code></p></td>
<td><p>Interpret any specified sequence as names instead of numeric sequence ids.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">STRING+</span></code></p></td>
<td><p>Specify one or more explicit sequences to extract, as sequence id, or sequence name if –names flag is set.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 6%" />
<col style="width: 10%" />
<col style="width: 85%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Utility</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-h</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--help</span></code></p></td>
<td><p>Prints help on command-line flag usage.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-Z</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-gzip</span></code></p></td>
<td><p>Set this flag when creating SAM format output to disable compression. By default SAM is compressed with blocked gzip, and BAM is always compressed.</p></td>
</tr>
</tbody>
</table>
<p><strong>Usage:</strong></p>
<p>Use the <code class="docutils literal notranslate"><span class="pre">sdf2sam</span></code> command to convert SDF data into unaligned SAM/BAM
format. By default all sequences will be extracted, but flags may be
specified to extract reads within a range, or explicitly specified reads
(either by numeric sequence id or by sequence name if <code class="docutils literal notranslate"><span class="pre">--names</span></code> is set).
This command is a useful way to export paired-end data to a single
output file while retaining any read group information that may be
stored in the SDF.</p>
<p>The output format is either SAM/BAM depending on the specified output file name.
e.g. <code class="docutils literal notranslate"><span class="pre">output.sam</span></code> or <code class="docutils literal notranslate"><span class="pre">output.sam.gz</span></code> will output as SAM, whereas
<code class="docutils literal notranslate"><span class="pre">output.bam</span></code> will output as BAM. If neither SAM or BAM format is indicated by
the file name then BAM will be used and the output file name adjusted
accordingly. e.g <code class="docutils literal notranslate"><span class="pre">output</span></code> will become <code class="docutils literal notranslate"><span class="pre">output.bam</span></code>. However if standard
output is selected (<code class="docutils literal notranslate"><span class="pre">-</span></code>) then the output will always be in uncompressed SAM
format.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">--start-id</span></code> and <code class="docutils literal notranslate"><span class="pre">--end-if</span></code> behave as in <code class="docutils literal notranslate"><span class="pre">sdf2fasta</span></code>.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#format"><span class="std std-ref">format</span></a>,
<a class="reference internal" href="#sdf2fasta"><span class="std std-ref">sdf2fasta</span></a>,
<a class="reference internal" href="#sdf2fastq"><span class="std std-ref">sdf2fastq</span></a>,
<a class="reference internal" href="#sdfstats"><span class="std std-ref">sdfstats</span></a>,
<a class="reference internal" href="#cg2sdf"><span class="std std-ref">cg2sdf</span></a>,
<a class="reference internal" href="#sdfsplit"><span class="std std-ref">sdfsplit</span></a></p>
</div>
</div>
<div class="section" id="fastqtrim">
<h3>fastqtrim<a class="headerlink" href="#fastqtrim" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>Trim reads in FASTQ files.</p>
<p><strong>Syntax:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg fastqtrim [OPTION]... -i FILE -o FILE
</pre></div>
</div>
<p><strong>Example:</strong></p>
<p>Apply hard base removal from the start of the read and quality-based trimming of terminal bases:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg fastqtrim -s 12 -E 18 -i S12_R1.fastq.gz -o S12_trimmed_R1.fastq.gz
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<table class="docutils align-default">
<colgroup>
<col style="width: 4%" />
<col style="width: 18%" />
<col style="width: 78%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>File Input/Output</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-i</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--input=FILE</span></code></p></td>
<td><p>Input FASTQ file, Use ‘-‘ to read from standard input.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-o</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--output=FILE</span></code></p></td>
<td><p>Output filename. Use ‘-‘ to write to standard output.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-q</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--quality-format=FORMAT</span></code></p></td>
<td><p>Quality data encoding method used in FASTQ input files (Illumina 1.8+ uses sanger). Allowed values are [sanger, solexa, illumina] (Default is sanger)</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 6%" />
<col style="width: 24%" />
<col style="width: 70%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Filtering</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--discard-empty-reads</span></code></p></td>
<td><p>Discard reads that have zero length after trimming. Should not be used with paired-end data.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-E</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--end-quality-threshold=INT</span></code></p></td>
<td><p>Trim read ends to maximise base quality above the given threshold (Default is 0)</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--min-read-length=INT</span></code></p></td>
<td><p>If a read ends up shorter than this threshold it will be trimmed to zero length (Default is 0)</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-S</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--start-quality-threshold=INT</span></code></p></td>
<td><p>Trim read starts to maximise base quality above the given threshold (Default is 0)</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-e</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--trim-end-bases=INT</span></code></p></td>
<td><p>Always trim the specified number of bases from read end (Default is 0)</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-s</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--trim-start-bases=INT</span></code></p></td>
<td><p>Always trim the specified number of bases from read start (Default is 0)</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 6%" />
<col style="width: 24%" />
<col style="width: 70%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Utility</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-h</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--help</span></code></p></td>
<td><p>Print help on command-line flag usage.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-Z</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-gzip</span></code></p></td>
<td><p>Do not gzip the output.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-r</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--reverse-complement</span></code></p></td>
<td><p>If set, output in reverse complement.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--seed=INT</span></code></p></td>
<td><p>Seed used during subsampling.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--subsample=FLOAT</span></code></p></td>
<td><p>If set, subsample the input to retain this fraction of reads.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-T</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--threads=INT</span></code></p></td>
<td><p>Number of threads (Default is the number of available cores)</p></td>
</tr>
</tbody>
</table>
<p><strong>Usage:</strong></p>
<p>Use <code class="docutils literal notranslate"><span class="pre">fastqtrim</span></code> to apply custom trimming and preprocessing to raw
FASTQ files prior to mapping and alignment. The <code class="docutils literal notranslate"><span class="pre">format</span></code> command
contains some limited trimming options, which are applied to all input
files, however in some cases different or specific trimming operations
need to be applied to the various input files. For example, for
paired-end data, different trimming may need to be applied for the left
read files compared to the right read files. In these cases,
<code class="docutils literal notranslate"><span class="pre">fastqtrim</span></code> should be used to process the FASTQ files first.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">--end-quality-threshold</span></code> flag can be used to trim poor quality bases
from the ends of the input reads by inspecting base qualities from FASTQ
input. If and only if the quality of the final base of the read is less
than the threshold given, a new read length is found which maximizes the
overall quality of the retained bases using the following formula:</p>
<div class="math">
<p><img src="_images/math/6c754ae3fc49dc56e236eb95ef00cfdcad3df594.png" alt="\arg \max x\left({\sum_{i=x+1}^l (T - q(i))}\right) \text{ if } q(l) &lt; T"/></p>
</div><p>where <em>l</em> is the original read length, <em>x</em> is the new read length, <em>T</em>
is the given threshold quality and <em>q(n)</em> is the quality of the base at
the position <em>n</em> of the read.  Similarly, <code class="docutils literal notranslate"><span class="pre">--start-quality-threshold</span></code>
can be used to apply this quality-based thresholding to the start of
reads.</p>
<p>Some of the trimming options may result in reads that have no bases
remaining. By default, these are output as zero-length FASTQ reads,
which RTG commands are able to handle normally. It is also possible to
remove zero-length reads altogether from the output with the
<code class="docutils literal notranslate"><span class="pre">--discard-empty-reads</span></code> option, however this should not be used when
processing FASTQ files corresponding to paired-end data, otherwise the
pairs in the two files will no longer be matched.</p>
<p>Similarly, when using the <code class="docutils literal notranslate"><span class="pre">--subsample</span></code> option to down-sample a FASTQ
file for paired-end data, you should specify an explicit randomization
seed via <code class="docutils literal notranslate"><span class="pre">--seed</span></code> and use the same seed value for the left and right
files.</p>
<div class="section" id="formatting-with-filtering-on-the-fly">
<h4>Formatting with filtering on the fly<a class="headerlink" href="#formatting-with-filtering-on-the-fly" title="Permalink to this headline">¶</a></h4>
<p>Running custom filtering with <code class="docutils literal notranslate"><span class="pre">fastqtrim</span></code> need not mean that
additional disk space is required or that formatting be slowed down due
to additional disk I/O.  It is possible when using standard unix shells
to perform the filtering on the fly.  The following example demonstrates
how to apply different trimming options to left and right files while
formatting to SDF:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg format -f fastq -o S12_trimmed.sdf \
    -l &lt;(rtg fastqtrim -s 12 -E 18 -i S12_R1.fastq.gz -o -)
    -r &lt;(rtg fastqtrim -E 18 -i S12_R2.fastq.gz -o -)
</pre></div>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#format"><span class="std std-ref">format</span></a></p>
</div>
</div>
</div>
<div class="section" id="petrim">
<h3>petrim<a class="headerlink" href="#petrim" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>Trim paired-end read FASTQ files based on read arm alignment overlap.</p>
<p><strong>Syntax:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg petrim [OPTION]... -l FILE -o FILE -r FILE
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<table class="docutils align-default">
<colgroup>
<col style="width: 4%" />
<col style="width: 17%" />
<col style="width: 79%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>File Input/Output</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-l</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--left=FILE</span></code></p></td>
<td><p>Left input FASTQ file (AKA R1)</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-o</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--output=FILE</span></code></p></td>
<td><p>Output filename prefix. Use ‘-‘ to write to standard output.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-q</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--quality-format=FORMAT</span></code></p></td>
<td><p>Quality data encoding method used in FASTQ input files (Illumina 1.8+ uses sanger). Allowed values are [sanger, solexa, illumina] (Default is sanger)</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-r</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--right=FILE</span></code></p></td>
<td><p>Right input FASTQ file (AKA R2)</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 6%" />
<col style="width: 22%" />
<col style="width: 72%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Sensitivity Tuning</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--aligner-band-width=FLOAT</span></code></p></td>
<td><p>Aligner indel band width scaling factor, fraction of read length allowed as an indel (Default is 0.5)</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--gap-extend-penalty=INT</span></code></p></td>
<td><p>Penalty for a gap extension during alignment (Default is 1)</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--gap-open-penalty=INT</span></code></p></td>
<td><p>Penalty for a gap open during alignment (Default is 19)</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-P</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--min-identity=INT</span></code></p></td>
<td><p>Minimum percent identity in overlap to trigger overlap trimming (Default is 90)</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-L</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--min-overlap-length=INT</span></code></p></td>
<td><p>Minimum number of bases in overlap to trigger overlap trimming (Default is 25)</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--mismatch-penalty=INT</span></code></p></td>
<td><p>Penalty for a mismatch during alignment (Default is 9)</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--soft-clip-distance=INT</span></code></p></td>
<td><p>Soft clip alignments if indels occur INT bp from either end (Default is 5)</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--unknowns-penalty=INT</span></code></p></td>
<td><p>Penalty for unknown nucleotides during alignment (Default is 5)</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 4%" />
<col style="width: 18%" />
<col style="width: 77%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Filtering</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--discard-empty-pairs</span></code></p></td>
<td><p>If set, discard pairs where both reads have zero length (after any trimming)</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--discard-empty-reads</span></code></p></td>
<td><p>If set, discard pairs where either read has zero length (after any trimming)</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--left-probe-length=INT</span></code></p></td>
<td><p>Assume R1 starts with probes this long, and trim R2 bases that overlap into this (Default is 0)</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-M</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--midpoint-merge</span></code></p></td>
<td><p>If set, merge overlapping reads at midpoint of overlap region. Result is in R1 (R2 will be empty)</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-m</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--midpoint-trim</span></code></p></td>
<td><p>If set, trim overlapping reads to midpoint of overlap region.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--min-read-length=INT</span></code></p></td>
<td><p>If a read ends up shorter than this threshold it will be trimmed to zero length (Default is 0)</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--mismatch-adjustment=STRING</span></code></p></td>
<td><p>Method used to alter bases/qualities at mismatches within overlap region. Allowed values are [none, zero-phred, pick-best] (Default is none)</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--right-probe-length=INT</span></code></p></td>
<td><p>Assume R2 starts with probes this long, and trim R1 bases that overlap into this (Default is 0)</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 6%" />
<col style="width: 23%" />
<col style="width: 71%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Utility</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-h</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--help</span></code></p></td>
<td><p>Print help on command-line flag usage.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--interleave</span></code></p></td>
<td><p>Interleave paired data into a single output file. Default is to split to separate output files.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-Z</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-gzip</span></code></p></td>
<td><p>Do not gzip the output.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--seed=INT</span></code></p></td>
<td><p>Seed used during subsampling.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--subsample=FLOAT</span></code></p></td>
<td><p>If set, subsample the input to retain this fraction of reads.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-T</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--threads=INT</span></code></p></td>
<td><p>Number of threads (Default is the number of available cores)</p></td>
</tr>
</tbody>
</table>
<p><strong>Usage:</strong></p>
<p>Paired-end read sequencing with read lengths that are long relative to
the typical library fragment size can often result in the same bases
being sequenced by both arms. This repeated sequencing of bases within
the same fragment can skew variant calling, and so it can be advantageous
to remove such read overlap.</p>
<p>In some cases, complete read-through can occur, resulting in additional
adaptor or non-genomic bases being present at the ends of reads.</p>
<p>In addition, some library preparation methods rely on the ligation of
synthetic probe sequence to attract target DNA, which is subsequently
sequenced.  Since these probe bases do not represent genomic material,
they must be removed at some point during the analytic pipeline prior to
variant calling, otherwise they could act as a reference bias when
calling variants. Removal from the primary arm where the probe is
attached is typically easy enough (e.g. via <code class="docutils literal notranslate"><span class="pre">fastqtrim</span></code>), however in
cases of high read overlap, probe sequence can also be present in the
other read arm.</p>
<p><code class="docutils literal notranslate"><span class="pre">petrim</span></code> aligns each read arm against it’s mate with high stringency
in order to identify cases of read overlap. The sensitivity of read
overlap detection is primarily controlled through the use of
<code class="docutils literal notranslate"><span class="pre">--min-identity</span></code> and <code class="docutils literal notranslate"><span class="pre">--min-overlap-length</span></code>, although it is also
possible to adjust the penalties used during alignment.</p>
<p>The following types of trimming or merging may be applied.</p>
<ul class="simple">
<li><p>Removal of non-genomic bases due to complete read-through. This
removal is always applied.</p></li>
<li><p>Removal of overlap bases impinging into regions occupied by probe
bases. For example, if the left arms contain 11-mer probes, using
<code class="docutils literal notranslate"><span class="pre">--left-probe-length=11</span></code> will result in the removal of any right arm
bases that overlap into the first 11 bases of the left arm. Similar
trimming is available for situations where probes are ligated to the
right arm by using <code class="docutils literal notranslate"><span class="pre">--right-probe-length</span></code>.</p></li>
<li><p>Adjustment of mismatching read bases inside areas of overlap. Such
mismatches indicate that one or other of the bases has been
incorrectly sequenced. Alteration of these bases is selected by
supplying the <code class="docutils literal notranslate"><span class="pre">--mismatch-adjustment</span></code> flag with a value of
<code class="docutils literal notranslate"><span class="pre">zero-phred</span></code> to alter the phred quality score of both bases to zero,
or <code class="docutils literal notranslate"><span class="pre">pick-best</span></code> to choose whichever base had the higher reported
quality score.</p></li>
<li><p>Removal of overlap regions by trimming both arms back to a point where
no overlap is present. An equal number of bases are removed from each
arm. This trimming is enabled by specifying <code class="docutils literal notranslate"><span class="pre">--midpoint-trim</span></code> and
takes place after any read-through or probe related trimming.</p></li>
<li><p>Merging non-redundant sequence from both reads to create a single
read, enabled via <code class="docutils literal notranslate"><span class="pre">--midpoint-merge</span></code>. This is like
<code class="docutils literal notranslate"><span class="pre">--midpoint-trim</span></code> with a subsequent moving of the R2 read onto the
end of the the R1 read (thus the R2 read becomes empty).</p></li>
</ul>
<p>After trimming or merging it is possible that one or both of the arms of
the pair have no bases remaining, and a strategy is needed to handle
these pairs. The default is to retain such pairs in the output, even if
one or both are zero-length.  When both arms are zero-length, the pair
can be dropped from output with the use of <code class="docutils literal notranslate"><span class="pre">--discard-empty-pairs</span></code>. If
downstream processing cannot handle zero-length reads,
<code class="docutils literal notranslate"><span class="pre">--discard-empty-reads</span></code> will drop a read pair if either of the arms is
zero-length.</p>
<p><code class="docutils literal notranslate"><span class="pre">petrim</span></code> also provides the ability to down-sample a read set by using
the <code class="docutils literal notranslate"><span class="pre">--subsample</span></code> option. This will produce a different sampling each time,
unless an explicit randomization seed is specified via <code class="docutils literal notranslate"><span class="pre">--seed</span></code>.</p>
<div class="section" id="formatting-with-paired-end-trimming-on-the-fly">
<h4>Formatting with paired-end trimming on the fly<a class="headerlink" href="#formatting-with-paired-end-trimming-on-the-fly" title="Permalink to this headline">¶</a></h4>
<p>Running custom filtering with <code class="docutils literal notranslate"><span class="pre">petrim</span></code> can be done in standard Unix
shells without incurring the use of additional disk space or unduly
slowing down the formatting of reads. The following example demonstrates
how to apply paired-end trimming while formatting to SDF:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg format -f fastq-interleaved -o S12_trimmed.sdf \
    &lt;(rtg petrim -l S12_R1.fastq.gz -r S12_R2.fastq.gz -m -o - --interleaved)
</pre></div>
</div>
<p>This can even be combined with <code class="docutils literal notranslate"><span class="pre">fastqtrim</span></code> to provide extremely
flexible trimming:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg format -f fastq-interleaved -o S12_trimmed.sdf \
    &lt;(rtg petrim -m -o - --interleave \
         -l &lt;(rtg fastqtrim -s 12 -E 18 -i S12_R1.fastq.gz -o -) \
         -r &lt;(rtg fastqtrim -E 18 -i S12_R2.fastq.gz -o -) \
     )
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p><code class="docutils literal notranslate"><span class="pre">petrim</span></code> currently assumes Illumina paired-end sequencing,
and aligns the reads in FR orientation. Sequencing methods which
produce arms in a different orientation can be processed by first
converting the input files using <code class="docutils literal notranslate"><span class="pre">fastqtrim</span> <span class="pre">--reverse-complement</span></code>,
running <code class="docutils literal notranslate"><span class="pre">petrim</span></code>, followed by another <code class="docutils literal notranslate"><span class="pre">fastqtrim</span>
<span class="pre">--reverse-complement</span></code> to restore the reads to their original
orientation.</p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#fastqtrim"><span class="std std-ref">fastqtrim</span></a>,
<a class="reference internal" href="#format"><span class="std std-ref">format</span></a></p>
</div>
</div>
</div>
</div>
<div class="section" id="simulation-commands">
<h2>Simulation Commands<a class="headerlink" href="#simulation-commands" title="Permalink to this headline">¶</a></h2>
<p>RTG includes some simulation commands that may be useful for
experimenting with effects of various RTG command parameters or when
getting familiar with RTG work flows. A simple simulation series might
involve the following commands:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg genomesim --output sim-ref-sdf --min-length 500000 --max-length 5000000 \
  --num-contigs 5
$ rtg popsim --reference sim-ref-sdf --output population.vcf.gz
$ rtg samplesim --input population.vcf.gz --output sample1.vcf.gz \
  --output-sdf sample1-sdf --reference sim-ref-sdf --sample sample1
$ rtg readsim --input sample1-sdf --output reads-sdf --machine illumina_pe \
  -L 75 -R 75 --coverage 10
$ rtg map --template sim-ref-sdf --input reads-sdf --output sim-mapping \
  --sam-rg &quot;@RG\tID:sim-rg\tSM:sample1\tPL:ILLUMINA&quot;
$ rtg snp --template sim-ref-sdf --output sim-name-snp sim-mapping/alignments.bam
</pre></div>
</div>
<div class="section" id="genomesim">
<h3>genomesim<a class="headerlink" href="#genomesim" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>Use the <code class="docutils literal notranslate"><span class="pre">genomesim</span></code> command to simulate a reference genome, or to create
a baseline reference genome for a research project when an actual genome
reference sequence is unavailable.</p>
<p><strong>Syntax:</strong></p>
<p>Specify number of sequences, plus minimum and maximum lengths:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg genomesim [OPTION]... -o SDF --max-length INT --min-length INT -n INT
</pre></div>
</div>
<p>Specify explicit sequence lengths (one more sequences):</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg genomesim [OPTION]... -o SDF -l INT
</pre></div>
</div>
<p><strong>Example:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg genomesim -o genomeTest -l 500000
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<table class="docutils align-default">
<colgroup>
<col style="width: 16%" />
<col style="width: 33%" />
<col style="width: 51%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>File Input/Output</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-o</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--output=SDF</span></code></p></td>
<td><p>The name of the output SDF.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 6%" />
<col style="width: 17%" />
<col style="width: 77%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Utility</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--comment=STRING</span></code></p></td>
<td><p>Specify a comment to include in the generated SDF.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--freq=STRING</span></code></p></td>
<td><p>Set the relative frequencies of A,C,G,T in the generated sequence. (Default is 1,1,1,1).</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-h</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--help</span></code></p></td>
<td><p>Prints help on command-line flag usage.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-l</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--length=INT</span></code></p></td>
<td><p>Specify the length of generated sequence. May be specified 0 or more times, or as a comma separated list.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--max-length=INT</span></code></p></td>
<td><p>Specify the maximum sequence length.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--min-length=INT</span></code></p></td>
<td><p>Specify the minimum sequence length.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-n</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--num-contigs=INT</span></code></p></td>
<td><p>Specify the number of sequences to generate.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--prefix=STRING</span></code></p></td>
<td><p>Specify a sequence name prefix to be used for the generated sequences. The default is to name the output sequences
‘simulatedSequenceN’, where N is increasing for each sequence.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-s</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--seed=INT</span></code></p></td>
<td><p>Specify seed for the random number generator.</p></td>
</tr>
</tbody>
</table>
<p><strong>Usage:</strong></p>
<p>The <code class="docutils literal notranslate"><span class="pre">genomesim</span></code> command allows one to create a simulated genome with one
or more contiguous sequences - exact lengths of each contig or number of
contigs with minimum and maximum lengths provided. The contents of an
SDF directory created by <code class="docutils literal notranslate"><span class="pre">genomesim</span></code> can be exported to a FASTA file
using the <code class="docutils literal notranslate"><span class="pre">sdf2fasta</span></code> command.</p>
<p>This command is primarily useful for providing a simple randomly
generated base genome for use with subsequent simulation commands.</p>
<p>Each generated contig is named by appending an increasing numeric index
to the specified prefix. For example <code class="docutils literal notranslate"><span class="pre">--prefix=chr</span> <span class="pre">--num-contigs=10</span></code>
would yield contigs named <code class="docutils literal notranslate"><span class="pre">chr1</span></code> through <code class="docutils literal notranslate"><span class="pre">chr10</span></code>.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#cgsim"><span class="std std-ref">cgsim</span></a>,
<a class="reference internal" href="#readsim"><span class="std std-ref">readsim</span></a>,
<a class="reference internal" href="#popsim"><span class="std std-ref">popsim</span></a>,
<a class="reference internal" href="#samplesim"><span class="std std-ref">samplesim</span></a></p>
</div>
</div>
<div class="section" id="cgsim">
<h3>cgsim<a class="headerlink" href="#cgsim" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>Simulate Complete Genomics Inc sequencing reads. Supports the original 35 bp read structure (5-10-10-10), and the newer 29 bp read structure (10-9-10).</p>
<p><strong>Syntax:</strong></p>
<p>Generation by genomic coverage multiplier:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg cgsim [OPTION]... -V INT -t SDF -o SDF -c FLOAT
</pre></div>
</div>
<p>Generation by explicit number of reads:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg cgsim [OPTION]... -V INT -t SDF -o SDF -n INT
</pre></div>
</div>
<p><strong>Example:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg cgsim -V 1 -t HUMAN_reference -o CG_3x_readst -c 3
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<table class="docutils align-default">
<colgroup>
<col style="width: 6%" />
<col style="width: 24%" />
<col style="width: 71%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>File Input/Output</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-t</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--input=SDF</span></code></p></td>
<td><p>SDF containing input genome.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-o</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--output=SDF</span></code></p></td>
<td><p>Name for reads output SDF.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 6%" />
<col style="width: 24%" />
<col style="width: 71%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Fragment Generation</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--abundance</span></code></p></td>
<td><p>If set, the user-supplied distribution represents desired abundance.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-N</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--allow-unknowns</span></code></p></td>
<td><p>Allow reads to be drawn from template fragments containing unknown nucleotides.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-c</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--coverage=FLOAT</span></code></p></td>
<td><p>Coverage, must be positive.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-D</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--distribution=FILE</span></code></p></td>
<td><p>File containing probability distribution for sequence selection.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--dna-fraction</span></code></p></td>
<td><p>If set, the user-supplied distribution represents desired DNA fraction.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-M</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--max-fragment-size=INT</span></code></p></td>
<td><p>Maximum fragment size (Default is 500)</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-m</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--min-fragment-size=INT</span></code></p></td>
<td><p>Minimum fragment size (Default is 350)</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--n-rate=FLOAT</span></code></p></td>
<td><p>Rate that the machine will generate new unknowns in the read (Default is 0.0)</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-n</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--num-reads=INT</span></code></p></td>
<td><p>Number of reads to be generated.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--taxonomy-distribution=FILE</span></code></p></td>
<td><p>File containing probability distribution for sequence selection expressed by taxonomy id.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 9%" />
<col style="width: 25%" />
<col style="width: 66%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Complete Genomics</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-V</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--cg-read-version=INT</span></code></p></td>
<td><p>Select Complete Genomics read structure version, 1 (35 bp) or 2 (29 bp)</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 4%" />
<col style="width: 19%" />
<col style="width: 77%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Utility</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--comment=STRING</span></code></p></td>
<td><p>Comment to include in the generated SDF.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-h</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--help</span></code></p></td>
<td><p>Print help on command-line flag usage.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-names</span></code></p></td>
<td><p>Do not create read names in the output SDF.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-qualities</span></code></p></td>
<td><p>Do not create read qualities in the output SDF.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-q</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--qual-range=STRING</span></code></p></td>
<td><p>Set the range of base quality values permitted e.g.: 3-40 (Default is fixed qualities corresponding to overall machine base error rate)</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--sam-rg=STRING|FILE</span></code></p></td>
<td><p>File containing a single valid read group SAM header line or a string in the form <code class="docutils literal notranslate"><span class="pre">&#64;RG\tID:READGROUP1\tSM:BACT_SAMPLE\tPL:ILLUMINA</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-s</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--seed=INT</span></code></p></td>
<td><p>Seed for random number generator.</p></td>
</tr>
</tbody>
</table>
<p><strong>Usage:</strong></p>
<p>Use the <code class="docutils literal notranslate"><span class="pre">cgsim</span></code> command to set either <code class="docutils literal notranslate"><span class="pre">--coverage</span></code> or <code class="docutils literal notranslate"><span class="pre">--num-reads</span></code> in
simulated Complete Genomics reads. For more information about Complete
Genomics reads, refer to <a class="reference external" href="http://www.completegenomics.com">http://www.completegenomics.com</a></p>
<p>RTG simulation tools allows for deterministic experiment repetition. The
<code class="docutils literal notranslate"><span class="pre">--seed</span></code> parameter, for example, allows for regeneration of exact same
reads by setting the random number generator to be repeatable (without
supplying this flag a different set of reads will be generated each
time).</p>
<p>The <code class="docutils literal notranslate"><span class="pre">--distribution</span></code> parameter allows you to specify the probability
that a read will come from a particular named sequence for use with
metagenomic databases. Probabilities are numbers between zero and one
and must sum to one in the file.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#genomesim"><span class="std std-ref">genomesim</span></a>,
<a class="reference internal" href="#readsim"><span class="std std-ref">readsim</span></a>,
<a class="reference internal" href="#popsim"><span class="std std-ref">popsim</span></a>,
<a class="reference internal" href="#samplesim"><span class="std std-ref">samplesim</span></a></p>
</div>
</div>
<div class="section" id="readsim">
<h3>readsim<a class="headerlink" href="#readsim" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>Use the <code class="docutils literal notranslate"><span class="pre">readsim</span></code> command to generate single or paired end reads of
fixed or variable length from a reference genome, introducing machine
errors.</p>
<p><strong>Syntax:</strong></p>
<p>Generation by genomic coverage multiplier:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg readsim [OPTION]... -t SDF --machine STRING -o SDF -c FLOAT
</pre></div>
</div>
<p>Generation by explicit number of reads:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg readsim [OPTION]... -t SDF --machine STRING -o SDF -n INT
</pre></div>
</div>
<p><strong>Example:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg readsim -t genome_ref -o sim_reads -r 75 --machine illumina_se  -c 30
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<table class="docutils align-default">
<colgroup>
<col style="width: 4%" />
<col style="width: 17%" />
<col style="width: 79%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>File Input/Output</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-t</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--input=SDF</span></code></p></td>
<td><p>SDF containing input genome.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--machine=STRING</span></code></p></td>
<td><p>Select the sequencing technology to model. Allowed values are [illumina_se, illumina_pe, complete_genomics, complete_genomics_2, 454_pe, 454_se, iontorrent]</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-o</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--output=SDF</span></code></p></td>
<td><p>Name for reads output SDF.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 6%" />
<col style="width: 26%" />
<col style="width: 68%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Fragment Generation</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--abundance</span></code></p></td>
<td><p>If set, the user-supplied distribution represents desired abundance.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-N</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--allow-unknowns</span></code></p></td>
<td><p>Allow reads to be drawn from template fragments containing unknown nucleotides.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-c</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--coverage=FLOAT</span></code></p></td>
<td><p>Coverage, must be positive.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-D</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--distribution=FILE</span></code></p></td>
<td><p>File containing probability distribution for sequence selection.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--dna-fraction</span></code></p></td>
<td><p>If set, the user-supplied distribution represents desired DNA fraction.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-M</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--max-fragment-size=INT</span></code></p></td>
<td><p>Maximum fragment size (Default is 250)</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-m</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--min-fragment-size=INT</span></code></p></td>
<td><p>Minimum fragment size (Default is 200)</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--n-rate=FLOAT</span></code></p></td>
<td><p>Rate that the machine will generate new unknowns in the read (Default is 0.0)</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-n</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--num-reads=INT</span></code></p></td>
<td><p>Number of reads to be generated.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--taxonomy-distribution=FILE</span></code></p></td>
<td><p>File containing probability distribution for sequence selection expressed by taxonomy id.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 6%" />
<col style="width: 27%" />
<col style="width: 66%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Illumina PE</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-L</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--left-read-length=INT</span></code></p></td>
<td><p>Target read length on the left side.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-R</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--right-read-length=INT</span></code></p></td>
<td><p>Target read length on the right side.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 6%" />
<col style="width: 27%" />
<col style="width: 66%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Illumina SE</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-r</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--read-length=INT</span></code></p></td>
<td><p>Target read length, must be positive.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 6%" />
<col style="width: 25%" />
<col style="width: 69%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>454 SE/PE</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--454-max-total-size=INT</span></code></p></td>
<td><p>Maximum 454 read length (in paired end case the sum of the left and the right read lengths)</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--454-min-total-size=INT</span></code></p></td>
<td><p>Minimum 454 read length (in paired end case the sum of the left and the right read lengths)</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 6%" />
<col style="width: 27%" />
<col style="width: 66%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>IonTorrent SE</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--ion-max-total-size=INT</span></code></p></td>
<td><p>Maximum IonTorrent read length.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--ion-min-total-size=INT</span></code></p></td>
<td><p>Minimum IonTorrent read length.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 4%" />
<col style="width: 19%" />
<col style="width: 77%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Utility</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--comment=STRING</span></code></p></td>
<td><p>Comment to include in the generated SDF.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-h</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--help</span></code></p></td>
<td><p>Print help on command-line flag usage.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-names</span></code></p></td>
<td><p>Do not create read names in the output SDF.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-qualities</span></code></p></td>
<td><p>Do not create read qualities in the output SDF.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-q</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--qual-range=STRING</span></code></p></td>
<td><p>Set the range of base quality values permitted e.g.: 3-40 (Default is fixed qualities corresponding to overall machine base error rate)</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--sam-rg=STRING|FILE</span></code></p></td>
<td><p>File containing a single valid read group SAM header line or a string in the form <code class="docutils literal notranslate"><span class="pre">&#64;RG\tID:READGROUP1\tSM:BACT_SAMPLE\tPL:ILLUMINA</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-s</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--seed=INT</span></code></p></td>
<td><p>Seed for random number generator.</p></td>
</tr>
</tbody>
</table>
<p><strong>Usage:</strong></p>
<p>Create simulated reads from a reference genome by either specifying
coverage depth or a total number of reads.</p>
<p>A typical use case involves creating a mutated genome by introducing
SNPs or CNVs with <code class="docutils literal notranslate"><span class="pre">popsim</span></code> and <code class="docutils literal notranslate"><span class="pre">samplesim</span></code> generating reads from the
mutated genome with <code class="docutils literal notranslate"><span class="pre">readsim</span></code>, and mapping them back to the original
reference to verify the parameters used for mapping or variant
detection.</p>
<p>RTG simulation tools allows for deterministic experiment repetition. The
<code class="docutils literal notranslate"><span class="pre">--seed</span></code> parameter, for example, allows for regeneration of exact same
reads by setting the random number generator to be repeatable (without
supplying this flag a different set of reads will be generated each
time).</p>
<p>The <code class="docutils literal notranslate"><span class="pre">--distribution</span></code> parameter allows you to specify the sequence
composition of the resulting read set, primarily for use with
metagenomic databases.  The distribution file is a text file containing
lines of the form:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>&lt;probability&gt;&lt;space&gt;&lt;sequence name&gt;
</pre></div>
</div>
<p>Probabilities must be between zero and one and must sum to one in the
file. For reference databases containing taxonomy information, where
each species may be comprised of more than one sequence, it is instead
possible to use the <code class="docutils literal notranslate"><span class="pre">--taxonomy-distribution</span></code> option to specify the
probabilities at a per-species level. The format of each line in this
case is:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>&lt;probability&gt;&lt;space&gt;&lt;taxon id&gt;
</pre></div>
</div>
<p>When using <code class="docutils literal notranslate"><span class="pre">--distribution</span></code> or <code class="docutils literal notranslate"><span class="pre">--taxonomy-distribution</span></code>, the
interpretation must be specified one of <code class="docutils literal notranslate"><span class="pre">--abundance</span></code> or
<code class="docutils literal notranslate"><span class="pre">--dna-fraction</span></code>. When using <code class="docutils literal notranslate"><span class="pre">--abundance</span></code> each specified
probability reflects the chance of selecting the specified sequence
(or taxon id) from the set of sequences, and thus for a given abundance
a large sequence will be represented by more reads in the resulting set
than a short sequence. In contrast, with <code class="docutils literal notranslate"><span class="pre">--dna-fraction</span></code> each
specified probability reflects the chance of a read being derived
from the designated sequence, and thus for a given fraction, a large
sequence will have a lower depth of coverage than a short sequence.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#cgsim"><span class="std std-ref">cgsim</span></a>,
<a class="reference internal" href="#genomesim"><span class="std std-ref">genomesim</span></a>,
<a class="reference internal" href="#popsim"><span class="std std-ref">popsim</span></a>,
<a class="reference internal" href="#samplesim"><span class="std std-ref">samplesim</span></a></p>
</div>
</div>
<div class="section" id="popsim">
<h3>popsim<a class="headerlink" href="#popsim" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>Use the <code class="docutils literal notranslate"><span class="pre">popsim</span></code> command to generate a VCF containing simulated
population variants. Each variant allele generated has an associated
frequency <code class="docutils literal notranslate"><span class="pre">INFO</span></code> field describing how frequent in the population that
allele is.</p>
<p><strong>Syntax:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg popsim [OPTION]... -o FILE -t SDF
</pre></div>
</div>
<p><strong>Example:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg popsim -o pop.vcf -t HUMAN_reference
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<table class="docutils align-default">
<colgroup>
<col style="width: 7%" />
<col style="width: 19%" />
<col style="width: 74%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>File Input/Output</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-o</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--output=FILE</span></code></p></td>
<td><p>Output VCF file name.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-t</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--reference=SDF</span></code></p></td>
<td><p>SDF containing the reference genome.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 7%" />
<col style="width: 19%" />
<col style="width: 74%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Utility</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-h</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--help</span></code></p></td>
<td><p>Print help on command-line flag usage.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-Z</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-gzip</span></code></p></td>
<td><p>Do not gzip the output.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--seed=INT</span></code></p></td>
<td><p>Seed for the random number generator.</p></td>
</tr>
</tbody>
</table>
<p><strong>Usage:</strong></p>
<p>The <code class="docutils literal notranslate"><span class="pre">popsim</span></code> command is used to create a VCF containing variants with
frequency in population information that can be subsequently used to
simulate individual samples using the <code class="docutils literal notranslate"><span class="pre">samplesim</span></code> command. The frequency
in population is contained in a VCF <code class="docutils literal notranslate"><span class="pre">INFO</span></code> field called <code class="docutils literal notranslate"><span class="pre">AF</span></code>. The types
of variants and the allele-frequency distribution has been drawn from
observed variants and allele frequency distribution in human studies.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#readsim"><span class="std std-ref">readsim</span></a>,
<a class="reference internal" href="#genomesim"><span class="std std-ref">genomesim</span></a>,
<a class="reference internal" href="#samplesim"><span class="std std-ref">samplesim</span></a>,
<a class="reference internal" href="#childsim"><span class="std std-ref">childsim</span></a>,
<a class="reference internal" href="#samplereplay"><span class="std std-ref">samplereplay</span></a></p>
</div>
</div>
<div class="section" id="samplesim">
<h3>samplesim<a class="headerlink" href="#samplesim" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>Use the <code class="docutils literal notranslate"><span class="pre">samplesim</span></code> command to generate a VCF containing a genotype
simulated from population variants according to allele frequency.</p>
<p><strong>Syntax:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg samplesim [OPTION]... -i FILE -o FILE -t SDF -s STRING
</pre></div>
</div>
<p><strong>Example:</strong></p>
<p>From a population frequency VCF:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg samplesim -i pop.vcf -o 1samples.vcf -t HUMAN_reference -s person1 --sex male
</pre></div>
</div>
<p>From an existing simulated VCF:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg samplesim -i 1samples.vcf -o 2samples.vcf -t HUMAN_reference -s person2 \
  --sex female
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<table class="docutils align-default">
<colgroup>
<col style="width: 7%" />
<col style="width: 20%" />
<col style="width: 73%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>File Input/Output</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-i</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--input=FILE</span></code></p></td>
<td><p>Input VCF containing population variants.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-o</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--output=FILE</span></code></p></td>
<td><p>Output VCF file name.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--output-sdf=SDF</span></code></p></td>
<td><p>If set, output an SDF containing the sample genome.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-t</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--reference=SDF</span></code></p></td>
<td><p>SDF containing the reference genome.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-s</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--sample=STRING</span></code></p></td>
<td><p>Name for sample.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 7%" />
<col style="width: 21%" />
<col style="width: 72%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Utility</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--allow-missing-af</span></code></p></td>
<td><p>If set, treat variants without allele frequency annotation as uniformly likely.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-h</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--help</span></code></p></td>
<td><p>Print help on command-line flag usage.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-Z</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-gzip</span></code></p></td>
<td><p>Do not gzip the output.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--ploidy=STRING</span></code></p></td>
<td><p>Ploidy to use. Allowed values are [auto, diploid, haploid] (Default is auto)</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--seed=INT</span></code></p></td>
<td><p>Seed for the random number generator.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--sex=SEX</span></code></p></td>
<td><p>Sex of individual. Allowed values are [male, female, either] (Default is either)</p></td>
</tr>
</tbody>
</table>
<p><strong>Usage:</strong></p>
<p>The <code class="docutils literal notranslate"><span class="pre">samplesim</span></code> command is used to simulate an individuals genotype
information from a population variant frequency VCF generated by the
<code class="docutils literal notranslate"><span class="pre">popsim</span></code> command or by previous <code class="docutils literal notranslate"><span class="pre">samplesim</span></code> or <code class="docutils literal notranslate"><span class="pre">childsim</span></code> commands. The
new output VCF will contain all the existing variants and samples with a
new column for the new sample. The genotype at each record of the VCF
will be chosen randomly according to the allele frequency specified in
the <code class="docutils literal notranslate"><span class="pre">AF</span></code> field.</p>
<p>If input VCF records do not contain an <code class="docutils literal notranslate"><span class="pre">AF</span></code> annotation, by default any
ALT allele in that record will not be selected and so the sample will be
genotyped as 0/0. Alternatively for simple simulations the
<code class="docutils literal notranslate"><span class="pre">--allow-missing-af</span></code> flag will treat each allele in such records as
being equally likely (i.e.: effectively equivalent to <code class="docutils literal notranslate"><span class="pre">AF=0.5</span></code> for a
biallelic variant, <code class="docutils literal notranslate"><span class="pre">AF=0.33,0.33</span></code> for a triallelic variant, etc).</p>
<p>The ploidy for each genotype is automatically determined according to
the ploidy of that chromosome for the specified sex of the individual,
as defined in the reference genome <code class="docutils literal notranslate"><span class="pre">reference.txt</span></code> file. For more
information see <a class="reference internal" href="appendix.html#rtg-reference-file-format"><span class="std std-ref">RTG reference file format</span></a>. If the reference SDF
does not contain chromosome configuration information, a default ploidy
can be specified using the <code class="docutils literal notranslate"><span class="pre">--ploidy</span></code> flag.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">--output-sdf</span></code> flag can be used to optionally generate an SDF of the
individuals genotype which can then be used by the <code class="docutils literal notranslate"><span class="pre">readsim</span></code> command to
simulate a read set for the individual.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#readsim"><span class="std std-ref">readsim</span></a>,
<a class="reference internal" href="#genomesim"><span class="std std-ref">genomesim</span></a>,
<a class="reference internal" href="#popsim"><span class="std std-ref">popsim</span></a>,
<a class="reference internal" href="#childsim"><span class="std std-ref">childsim</span></a>,
<a class="reference internal" href="#samplereplay"><span class="std std-ref">samplereplay</span></a></p>
</div>
</div>
<div class="section" id="denovosim">
<h3>denovosim<a class="headerlink" href="#denovosim" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>Use the <code class="docutils literal notranslate"><span class="pre">denovosim</span></code> command to generate a VCF containing a derived
genotype containing <em>de novo</em> variants.</p>
<p><strong>Syntax:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg denovosim [OPTION]... -i FILE --original STRING -o FILE -t SDF -s STRING
</pre></div>
</div>
<p><strong>Example:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg denovosim -i sample.vcf --original personA -o 2samples.vcf \
  -t HUMAN_reference -s personB
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<table class="docutils align-default">
<colgroup>
<col style="width: 10%" />
<col style="width: 24%" />
<col style="width: 66%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>File Input/Output</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-i</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--input=FILE</span></code></p></td>
<td><p>The input VCF containing parent variants.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--original=STRING</span></code></p></td>
<td><p>The name of the existing sample to use as the original genotype.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-o</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--output=FILE</span></code></p></td>
<td><p>The output VCF file name.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--output-sdf=FILE</span></code></p></td>
<td><p>Set to output an SDF of the genome generated.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-t</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--reference=SDF</span></code></p></td>
<td><p>The SDF containing the reference genome.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-s</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--sample=STRING</span></code></p></td>
<td><p>The name for the new derived sample.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 5%" />
<col style="width: 15%" />
<col style="width: 80%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Utility</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-h</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--help</span></code></p></td>
<td><p>Prints help on command-line flag usage.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-Z</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-gzip</span></code></p></td>
<td><p>Set this flag to create the VCF output file without compression.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--num-mutations=INT</span></code></p></td>
<td><p>Set the expected number of de novo mutations per genome (Default is 70).</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--ploidy=STRING</span></code></p></td>
<td><p>The ploidy to use when the reference genome does not contain a reference text file. Allowed values are [auto, diploid, haploid] (Default is auto)</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--seed=INT</span></code></p></td>
<td><p>Set the seed for the random number generator.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--show-mutations</span></code></p></td>
<td><p>Set this flag to display information regarding de novo mutation points.</p></td>
</tr>
</tbody>
</table>
<p><strong>Usage:</strong></p>
<p>The <code class="docutils literal notranslate"><span class="pre">denovosim</span></code> command is used to simulate a derived genotype
containing <em>de novo</em> variants from a VCF containing an existing
genotype.</p>
<p>The output VCF will contain all the existing variants and samples, along
with additional <em>de novo</em> variants.  If the original and derived sample
names are different, the output will contain a new column for the
mutated sample. If the original and derived sample names are the same,
the sample in the output VCF is updated rather than creating an entirely
new sample column. When a sample receives a <em>de novo</em> mutation, the
sample <code class="docutils literal notranslate"><span class="pre">DN</span></code> field is set to “Y”.</p>
<p>If <em>de novo</em> variants were introduced without regard to neighboring
variants, a situation could arise where it is not possible to
unambiguously determine the haplotype of the simulated sample. To
prevent this, <code class="docutils literal notranslate"><span class="pre">denovosim</span></code> will not output a <em>de novo</em> variant that
overlaps existing variants. Since <code class="docutils literal notranslate"><span class="pre">denovosim</span></code> chooses candidate <em>de
novo</em> locations before reading the input VCF, this occasionally mandates
skipping a candidate <em>de novo</em> so the target number of mutations may not
always be reached.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">--output-sdf</span></code> flag can be used to optionally generate an SDF of the
derived genome which can then be used by the <code class="docutils literal notranslate"><span class="pre">readsim</span></code> command to
simulate a read set for the new genome.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#readsim"><span class="std std-ref">readsim</span></a>,
<a class="reference internal" href="#genomesim"><span class="std std-ref">genomesim</span></a>,
<a class="reference internal" href="#popsim"><span class="std std-ref">popsim</span></a>,
<a class="reference internal" href="#samplesim"><span class="std std-ref">samplesim</span></a>,
<a class="reference internal" href="#samplereplay"><span class="std std-ref">samplereplay</span></a></p>
</div>
</div>
<div class="section" id="childsim">
<h3>childsim<a class="headerlink" href="#childsim" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>Use the <code class="docutils literal notranslate"><span class="pre">childsim</span></code> command to generate a VCF containing a genotype
simulated as a child of two parents.</p>
<p><strong>Syntax:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg childsim [OPTION]... --father STRING -i FILE --mother STRING -o FILE -t SDF \
  -s STRING
</pre></div>
</div>
<p><strong>Example:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg childsim --father person1 --mother person2 -i 2samples.vcf -o 3samples.vcf \
  -t HUMAN_reference -s person3
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<table class="docutils align-default">
<colgroup>
<col style="width: 7%" />
<col style="width: 24%" />
<col style="width: 69%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>File Input/Output</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--father=STRING</span></code></p></td>
<td><p>Name of the existing sample to use as the father.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-i</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--input=FILE</span></code></p></td>
<td><p>Input VCF containing parent variants.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--mother=STRING</span></code></p></td>
<td><p>Name of the existing sample to use as the mother.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-o</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--output=FILE</span></code></p></td>
<td><p>Output VCF file name.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--output-sdf=SDF</span></code></p></td>
<td><p>If set, output an SDF containing the sample genome.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-t</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--reference=SDF</span></code></p></td>
<td><p>SDF containing the reference genome.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-s</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--sample=STRING</span></code></p></td>
<td><p>Name for new child sample.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 7%" />
<col style="width: 25%" />
<col style="width: 68%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Utility</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--extra-crossovers=FLOAT</span></code></p></td>
<td><p>Probability of extra crossovers per chromosome (Default is 0.01)</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--genetic-map-dir=DIR</span></code></p></td>
<td><p>If set, load genetic maps from this directory for recombination point selection.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-h</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--help</span></code></p></td>
<td><p>Print help on command-line flag usage.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-Z</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-gzip</span></code></p></td>
<td><p>Do not gzip the output.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--ploidy=STRING</span></code></p></td>
<td><p>Ploidy to use. Allowed values are [auto, diploid, haploid] (Default is auto)</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--seed=INT</span></code></p></td>
<td><p>Seed for the random number generator.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--sex=SEX</span></code></p></td>
<td><p>Sex of individual. Allowed values are [male, female, either] (Default is either)</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--show-crossovers</span></code></p></td>
<td><p>If set, display information regarding haplotype selection and crossover points.</p></td>
</tr>
</tbody>
</table>
<p><strong>Usage:</strong></p>
<p>The <code class="docutils literal notranslate"><span class="pre">childsim</span></code> command is used to simulate an individuals genotype
information from a VCF containing the two parent genotypes generated by
previous <code class="docutils literal notranslate"><span class="pre">samplesim</span></code> or <code class="docutils literal notranslate"><span class="pre">childsim</span></code> commands. The new output VCF will
contain all the existing variants and samples with a new column for the
new sample.</p>
<p>The ploidy for each genotype is generated according to the ploidy of
that chromosome for the specified sex of the individual, as defined in
the reference genome <code class="docutils literal notranslate"><span class="pre">reference.txt</span></code> file. For more information see
<a class="reference internal" href="appendix.html#rtg-reference-file-format"><span class="std std-ref">RTG reference file format</span></a>. The generated genotypes are all consistent
with Mendelian inheritance (<em>de novo</em> variants can be simulated with the
<code class="docutils literal notranslate"><span class="pre">denovosim</span></code> command).</p>
<p>The <code class="docutils literal notranslate"><span class="pre">--output-sdf</span></code> flag can be used to optionally generate an SDF of the
child’s genotype which can then be used by the <code class="docutils literal notranslate"><span class="pre">readsim</span></code> command to
simulate a read set for the child.</p>
<p>By default positions for crossover events are chosen according to a
uniform distribution.  However, if linkage information is available,
then this can be used to inform the crossover selection procedure.
The expected format for this information is described in
<a class="reference internal" href="appendix.html#genetic-map-directory"><span class="std std-ref">Genetic map directory</span></a>, and the directory containing the relevant
files can be specified by using the <code class="docutils literal notranslate"><span class="pre">--genetic-map-dir</span></code> flag.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#readsim"><span class="std std-ref">readsim</span></a>,
<a class="reference internal" href="#genomesim"><span class="std std-ref">genomesim</span></a>,
<a class="reference internal" href="#popsim"><span class="std std-ref">popsim</span></a>,
<a class="reference internal" href="#samplesim"><span class="std std-ref">samplesim</span></a>,
<a class="reference internal" href="#samplereplay"><span class="std std-ref">samplereplay</span></a></p>
</div>
</div>
<div class="section" id="pedsamplesim">
<h3>pedsamplesim<a class="headerlink" href="#pedsamplesim" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>Generates simulated genotypes for all members of a
pedigree. <code class="docutils literal notranslate"><span class="pre">pedsamplesim</span></code> automatically simulates founder individuals,
inheritance by children, and de novo mutations.</p>
<p><strong>Syntax:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg pedsamplesim [OPTION]... -i FILE -o DIR -p FILE -t SDF
</pre></div>
</div>
<p><strong>Example:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg pedsamplesim -t reference.sdf -p family.ped -i popvars.vcf \
  -o family_sim --remove-unused
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<table class="docutils align-default">
<colgroup>
<col style="width: 7%" />
<col style="width: 25%" />
<col style="width: 68%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>File Input/Output</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-i</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--input=FILE</span></code></p></td>
<td><p>Input VCF containing parent variants.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-o</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--output=DIR</span></code></p></td>
<td><p>Directory for output.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--output-sdf</span></code></p></td>
<td><p>If set, output an SDF for the genome of each simulated sample.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-p</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--pedigree=FILE</span></code></p></td>
<td><p>Genome relationships PED file.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-t</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--reference=SDF</span></code></p></td>
<td><p>SDF containing the reference genome.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 7%" />
<col style="width: 25%" />
<col style="width: 68%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Utility</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--extra-crossovers=FLOAT</span></code></p></td>
<td><p>Probability of extra crossovers per chromosome (Default is 0.01)</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--genetic-map-dir=DIR</span></code></p></td>
<td><p>If set, load genetic maps from this directory for recombination point selection.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-h</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--help</span></code></p></td>
<td><p>Print help on command-line flag usage.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-Z</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-gzip</span></code></p></td>
<td><p>Do not gzip the output.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--num-mutations=INT</span></code></p></td>
<td><p>Expected number of mutations per genome (Default is 70)</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--ploidy=STRING</span></code></p></td>
<td><p>Ploidy to use. Allowed values are [auto, diploid, haploid] (Default is auto)</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--remove-unused</span></code></p></td>
<td><p>If set, output only variants used by at least one sample.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--seed=INT</span></code></p></td>
<td><p>Seed for the random number generator.</p></td>
</tr>
</tbody>
</table>
<p><strong>Usage:</strong></p>
<p>The <code class="docutils literal notranslate"><span class="pre">pedsamplesim</span></code> uses the methods of <code class="docutils literal notranslate"><span class="pre">samplesim</span></code>, <code class="docutils literal notranslate"><span class="pre">denovosim</span></code>,
and <code class="docutils literal notranslate"><span class="pre">childsim</span></code> to greatly ease the simulation of multiple samples. The
input VCF should contain standard allele frequency INFO annotations that
will be used to simulate genotypes for any sample identified as a
founder. Any samples present in the pedigree that are already present in
the input VCF will not be regenerated. To simulate genotypes for a
subset of the members of the pedigree, use <code class="docutils literal notranslate"><span class="pre">pedfilter</span></code> to create a
filtered pedigree file that includes only the subset required.</p>
<p>The supplied pedigree file is first examined to identify any individuals
that cannot be simulated according to inheritance from other samples in
the pedigree. Note that simulation according to inheritance requires
both parents to be present in the pedigree.  These samples in the
pedigree are treated as founder individuals.</p>
<p>Founder individuals are simulated using <code class="docutils literal notranslate"><span class="pre">samplesim</span></code>, where the
genotypes are chosen according to the allele frequency annotation in the
input VCF.</p>
<p>All newly generated samples may have <em>de novo</em> mutations introduced
according to the <code class="docutils literal notranslate"><span class="pre">--num-mutations</span></code> setting. As with the <code class="docutils literal notranslate"><span class="pre">denovosim</span></code>
command, any <em>de novo</em> mutations introduced in a sample will be
genotyped as homozygous reference in other pre-existing samples, and
introduced variants will not overlap any pre-existing variant loci.</p>
<p>Samples that can be simulated according to Mendelian inheritance are
then generated, using <code class="docutils literal notranslate"><span class="pre">childsim</span></code>. As expected, as well as inheriting
<em>de novo</em> variants from parents, each child may obtain new <em>de novo</em>
mutations of their own.</p>
<p>If the simulated samples will be used for subsequent simulated
sequencing, such as via <code class="docutils literal notranslate"><span class="pre">readsim</span></code>, it is possible to automatically
output an SDF containing the simulated genome for each sample by
specifying the <code class="docutils literal notranslate"><span class="pre">--output-sdf</span></code> option, obviating the need to separately
use <code class="docutils literal notranslate"><span class="pre">samplereplay</span></code>.</p>
<p>By default positions for crossover events are chosen according to a
uniform distribution.  However, if linkage information is available,
then this can be used to inform the crossover selection procedure.
The expected format for this information is described in
<a class="reference internal" href="appendix.html#genetic-map-directory"><span class="std std-ref">Genetic map directory</span></a>, and the directory containing the relevant
files can be specified by using the <code class="docutils literal notranslate"><span class="pre">--genetic-map-dir</span></code> flag.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#pedfilter"><span class="std std-ref">pedfilter</span></a>,
<a class="reference internal" href="#popsim"><span class="std std-ref">popsim</span></a>,
<a class="reference internal" href="#samplesim"><span class="std std-ref">samplesim</span></a>,
<a class="reference internal" href="#childsim"><span class="std std-ref">childsim</span></a>,
<a class="reference internal" href="#denovosim"><span class="std std-ref">denovosim</span></a>,
<a class="reference internal" href="#samplereplay"><span class="std std-ref">samplereplay</span></a>,
<a class="reference internal" href="#readsim"><span class="std std-ref">readsim</span></a></p>
</div>
</div>
<div class="section" id="samplereplay">
<h3>samplereplay<a class="headerlink" href="#samplereplay" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>Use the <code class="docutils literal notranslate"><span class="pre">samplereplay</span></code> command to generate the genome SDF corresponding
to a sample genotype in a VCF file.</p>
<p><strong>Syntax:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg samplereplay [OPTION]... -i FILE -o SDF -t SDF -s STRING
</pre></div>
</div>
<p><strong>Example:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg samplereplay -i 3samples.vcf -o child.sdf -t HUMAN_reference -s person3
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<table class="docutils align-default">
<colgroup>
<col style="width: 7%" />
<col style="width: 19%" />
<col style="width: 74%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>File Input/Output</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-i</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--input=FILE</span></code></p></td>
<td><p>Input VCF containing the sample genotype.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-o</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--output=SDF</span></code></p></td>
<td><p>Name for output SDF.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-t</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--reference=SDF</span></code></p></td>
<td><p>SDF containing the reference genome.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-s</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--sample=STRING</span></code></p></td>
<td><p>Name of the sample to select from the VCF.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 7%" />
<col style="width: 19%" />
<col style="width: 74%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Utility</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-h</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--help</span></code></p></td>
<td><p>Print help on command-line flag usage.</p></td>
</tr>
</tbody>
</table>
<p><strong>Usage:</strong></p>
<p>The <code class="docutils literal notranslate"><span class="pre">samplereplay</span></code> command can be used to generate an SDF of a genotype
for a given sample from an existing VCF file. This can be used to
generate a genome from the outputs of the <code class="docutils literal notranslate"><span class="pre">samplesim</span></code> and <code class="docutils literal notranslate"><span class="pre">childsim</span></code>
commands. The output genome can then be used in simulating a read set
for the sample using the <code class="docutils literal notranslate"><span class="pre">readsim</span></code> command.</p>
<p>Every chromosome for which the individual is diploid will have two
sequences in the resulting SDF.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#readsim"><span class="std std-ref">readsim</span></a>,
<a class="reference internal" href="#genomesim"><span class="std std-ref">genomesim</span></a>,
<a class="reference internal" href="#popsim"><span class="std std-ref">popsim</span></a>,
<a class="reference internal" href="#samplesim"><span class="std std-ref">samplesim</span></a>,
<a class="reference internal" href="#childsim"><span class="std std-ref">childsim</span></a></p>
</div>
</div>
</div>
<div class="section" id="utility-commands">
<h2>Utility Commands<a class="headerlink" href="#utility-commands" title="Permalink to this headline">¶</a></h2>
<div class="section" id="bgzip">
<h3>bgzip<a class="headerlink" href="#bgzip" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>Block compress a file or decompress a block compressed file. Block
compressed outputs from the mapping and variant detection commands can
be indexed with the <code class="docutils literal notranslate"><span class="pre">index</span></code> command. They can also be processed with
standard gzip tools such as <code class="docutils literal notranslate"><span class="pre">gunzip</span></code> and <code class="docutils literal notranslate"><span class="pre">zcat</span></code>.</p>
<p><strong>Syntax:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg bgzip [OPTION]... FILE+
</pre></div>
</div>
<p><strong>Example:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg bgzip alignments.sam
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<table class="docutils align-default">
<colgroup>
<col style="width: 6%" />
<col style="width: 21%" />
<col style="width: 73%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>File Input/Output</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-l</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--compression-level=INT</span></code></p></td>
<td><p>The compression level to use, between 1 (least but fast) and 9 (highest but slow) (Default is 5)</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-d</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--decompress</span></code></p></td>
<td><p>Decompress.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-f</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--force</span></code></p></td>
<td><p>Force overwrite of output file.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-terminate</span></code></p></td>
<td><p>If set, do not add the block gzip termination block.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-c</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--stdout</span></code></p></td>
<td><p>Write on standard output, keep original files unchanged. Implied when using standard input.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">FILE+</span></code></p></td>
<td><p>File to (de)compress, use ‘-‘ for standard input. Must be specified 1 or more times.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 6%" />
<col style="width: 21%" />
<col style="width: 73%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Utility</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-h</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--help</span></code></p></td>
<td><p>Print help on command-line flag usage.</p></td>
</tr>
</tbody>
</table>
<p><strong>Usage:</strong></p>
<p>Use the <code class="docutils literal notranslate"><span class="pre">bgzip</span></code> command to block compress files. Files such as VCF, BED,
SAM, TSV must be block-compressed before they can be indexed for fast
retrieval of records corresponding to specific genomic regions.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#index"><span class="std std-ref">index</span></a></p>
</div>
</div>
<div class="section" id="index">
<h3>index<a class="headerlink" href="#index" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>Create tabix index files for block compressed TAB-delimited genome
position data files or BAM index files for BAM files.</p>
<p><strong>Syntax:</strong></p>
<p>Multi-file input specified from command line:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg index [OPTION]... FILE+
</pre></div>
</div>
<p>Multi-file input specified in a text file:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg index [OPTION]... -I FILE
</pre></div>
</div>
<p><strong>Example:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg index -f sam alignments.sam.gz
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<table class="docutils align-default">
<colgroup>
<col style="width: 5%" />
<col style="width: 19%" />
<col style="width: 76%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>File Input/Output</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-f</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--format=FORMAT</span></code></p></td>
<td><p>Format of input to index. Allowed values are [sam, bam, cram, sv, coveragetsv, bed, vcf, auto] (Default is auto)</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-I</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--input-list-file=FILE</span></code></p></td>
<td><p>File containing a list of block compressed files (1 per line) containing genome position data.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">FILE+</span></code></p></td>
<td><p>Block compressed files containing data to be indexed. May be specified 0 or more times.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 6%" />
<col style="width: 20%" />
<col style="width: 74%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Utility</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-h</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--help</span></code></p></td>
<td><p>Print help on command-line flag usage.</p></td>
</tr>
</tbody>
</table>
<p><strong>Usage:</strong></p>
<p>Use the <code class="docutils literal notranslate"><span class="pre">index</span></code> command to produce tabix indexes for block compressed
genome position data files like SAM files, VCF files, BED files, and the
TSV output from RTG commands such as <code class="docutils literal notranslate"><span class="pre">coverage</span></code>. The <code class="docutils literal notranslate"><span class="pre">index</span></code> command
can also be used to produce BAM indexes for BAM files with no index.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#map"><span class="std std-ref">map</span></a>,
<a class="reference internal" href="#coverage"><span class="std std-ref">coverage</span></a>,
<a class="reference internal" href="#snp"><span class="std std-ref">snp</span></a>,
<a class="reference internal" href="#extract"><span class="std std-ref">extract</span></a>,
<a class="reference internal" href="#bgzip"><span class="std std-ref">bgzip</span></a></p>
</div>
</div>
<div class="section" id="extract">
<h3>extract<a class="headerlink" href="#extract" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>Extract specified parts of an indexed block compressed genome position
data file.</p>
<p><strong>Syntax:</strong></p>
<p>Extract whole file:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg extract [OPTION]... FILE
</pre></div>
</div>
<p>Extract specific regions:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg extract [OPTION]... FILE STRING+
</pre></div>
</div>
<p><strong>Example:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg extract alignments.bam &#39;chr1:2500000~1000&#39;
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<table class="docutils align-default">
<colgroup>
<col style="width: 5%" />
<col style="width: 14%" />
<col style="width: 81%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>File Input/Output</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">FILE</span></code></p></td>
<td><p>The indexed block compressed genome position data file to extract.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 4%" />
<col style="width: 10%" />
<col style="width: 86%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Filtering</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">REGION+</span></code></p></td>
<td><p>The range to display. The format is one of &lt;sequence_name&gt;, &lt;sequence_name&gt;:&lt;start&gt;-&lt;end&gt;, &lt;sequence_name&gt;:&lt;pos&gt;+&lt;length&gt; or &lt;sequence_name&gt;:&lt;pos&gt;~&lt;padding&gt;.
May be specified 0 or more times.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 6%" />
<col style="width: 32%" />
<col style="width: 62%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Reporting</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--header</span></code></p></td>
<td><p>Set to also display the file header.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--header-only</span></code></p></td>
<td><p>Set to only display the file header.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 15%" />
<col style="width: 21%" />
<col style="width: 64%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Utility</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-h</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--help</span></code></p></td>
<td><p>Prints help on command-line flag usage.</p></td>
</tr>
</tbody>
</table>
<p><strong>Usage:</strong></p>
<p>Use the <code class="docutils literal notranslate"><span class="pre">extract</span></code> command to view specific parts of indexed block
compressed genome position data files such as those in SAM/BAM/BED/VCF
format.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#map"><span class="std std-ref">map</span></a>,
<a class="reference internal" href="#coverage"><span class="std std-ref">coverage</span></a>,
<a class="reference internal" href="#snp"><span class="std std-ref">snp</span></a>,
<a class="reference internal" href="#index"><span class="std std-ref">index</span></a>,
<a class="reference internal" href="#bgzip"><span class="std std-ref">bgzip</span></a></p>
</div>
</div>
<div class="section" id="aview">
<h3>aview<a class="headerlink" href="#aview" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>View read mapping and variants corresponding to a region of the genome,
with output as ASCII to the terminal, or HTML.</p>
<p><strong>Syntax:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg aview [OPTION]... --region STRING -t SDF FILE+
</pre></div>
</div>
<p><strong>Example:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg aview -t hg19 -b omni.vcf -c calls.vcf map/alignments.bam \
  --region Chr10:100000+3 –padding 30
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<table class="docutils align-default">
<colgroup>
<col style="width: 5%" />
<col style="width: 21%" />
<col style="width: 73%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>File Input/Output</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-b</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--baseline=FILE</span></code></p></td>
<td><p>VCF file containing baseline variants.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-B</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--bed=FILE</span></code></p></td>
<td><p>BED file containing regions to overlay. May be specified 0 or more times.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-c</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--calls=FILE</span></code></p></td>
<td><p>VCF file containing called variants. May be specified 0 or more times.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-I</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--input-list-file=FILE</span></code></p></td>
<td><p>File containing a list of SAM/BAM format files (1 per line)</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-r</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--reads=SDF</span></code></p></td>
<td><p>Read SDF (only needed to indicate correctness of simulated read mappings). May be specified 0 or more times.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-t</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--template=SDF</span></code></p></td>
<td><p>SDF containing the reference genome.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">FILE+</span></code></p></td>
<td><p>Alignment SAM/BAM files. May be specified 0 or more times.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 4%" />
<col style="width: 16%" />
<col style="width: 80%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Filtering</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-p</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--padding=INT</span></code></p></td>
<td><p>Padding around region of interest (Default is to automatically determine padding to avoid read truncation)</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--region=REGION</span></code></p></td>
<td><p>The region of interest to display. The format is one of &lt;sequence_name&gt;, &lt;sequence_name&gt;:&lt;start&gt;-&lt;end&gt;, &lt;sequence_name&gt;:&lt;pos&gt;+&lt;length&gt; or
&lt;sequence_name&gt;:&lt;pos&gt;~&lt;padding&gt;</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--sample=STRING</span></code></p></td>
<td><p>Specify name of sample to select. May be specified 0 or more times, or as a comma separated list.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 5%" />
<col style="width: 21%" />
<col style="width: 74%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Reporting</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--html</span></code></p></td>
<td><p>Output as HTML.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-base-colors</span></code></p></td>
<td><p>Do not use base-colors.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-color</span></code></p></td>
<td><p>Do not use colors.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-dots</span></code></p></td>
<td><p>Display nucleotide instead of dots.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--print-cigars</span></code></p></td>
<td><p>Print alignment cigars.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--print-mapq</span></code></p></td>
<td><p>Print alignment MAPQ values.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--print-mate-position</span></code></p></td>
<td><p>Print mate position.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--print-names</span></code></p></td>
<td><p>Print read names.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--print-readgroup</span></code></p></td>
<td><p>Print read group id for each alignment.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--print-reference-line=INT</span></code></p></td>
<td><p>Print reference line every N lines (Default is 0)</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--print-sample</span></code></p></td>
<td><p>Print sample id for each alignment.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--print-soft-clipped-bases</span></code></p></td>
<td><p>Print soft clipped bases.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--project-track=INT</span></code></p></td>
<td><p>If set, project highlighting for the specified track down through reads (Default projects the union of tracks)</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--sort-readgroup</span></code></p></td>
<td><p>Sort reads first on read group and then on start position.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--sort-reads</span></code></p></td>
<td><p>Sort reads on start position.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--sort-sample</span></code></p></td>
<td><p>Sort reads first on sample id and then on start position.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--unflatten</span></code></p></td>
<td><p>Display unflattened CGI reads when present.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 6%" />
<col style="width: 23%" />
<col style="width: 72%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Utility</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-h</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--help</span></code></p></td>
<td><p>Print help on command-line flag usage.</p></td>
</tr>
</tbody>
</table>
<p><strong>Usage:</strong></p>
<p>Use the <code class="docutils literal notranslate"><span class="pre">aview</span></code> command to display a textual view of mappings and
variants corresponding to a small region of the reference genome. This
is useful when examining evidence for variant calls in a server
environment where a graphical display application such as IGV is not
available. The <code class="docutils literal notranslate"><span class="pre">aview</span></code> command is easy to script in order to output
displays for multiple regions for later viewing (either as text or
HTML).</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#map"><span class="std std-ref">map</span></a>,
<a class="reference internal" href="#snp"><span class="std std-ref">snp</span></a></p>
</div>
</div>
<div class="section" id="sdfstats">
<h3>sdfstats<a class="headerlink" href="#sdfstats" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>Print statistics that describe a directory of SDF formatted data.</p>
<p><strong>Syntax:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg sdfstats [OPTION]... SDF+
</pre></div>
</div>
<p><strong>Example:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg sdfstats human_READS_SDF

Location           : C:\human_READS_SDF
Parameters         : format -f solexa -o human_READS_SDF
                                c:\users\Elle\human\SRR005490.fastq.gz
SDF Version        : 6
Type               : DNA
Source             : SOLEXA
Paired arm         : UNKNOWN
Number of sequences: 4193903
Maximum length     : 48
Minimum length     : 48
N                  : 931268
A                  : 61100096
C                  : 41452181
G                  : 45262380
T                  : 52561419
Total residues     : 201307344
Quality scores available on this SDF
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<table class="docutils align-default">
<colgroup>
<col style="width: 4%" />
<col style="width: 11%" />
<col style="width: 85%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>File Input/Output</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">SDF+</span></code></p></td>
<td><p>Specifies an SDF on which statistics are to be reported. May be specified 1 or more times.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 5%" />
<col style="width: 9%" />
<col style="width: 86%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Reporting</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--lengths</span></code></p></td>
<td><p>Set to print out the name and length of each sequence. (Not recommended for read sets).</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-p</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--position</span></code></p></td>
<td><p>Set to include information about unknown bases (Ns) by read position.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-q</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--quality</span></code></p></td>
<td><p>Set to display mean of quality.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--sex=SEX</span></code></p></td>
<td><p>Set to display the reference sequence list for the given sex. Allowed values are [male, female, either]. May be specified 0 or more times, or as a comma separated list.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--taxonomy</span></code></p></td>
<td><p>Set to display information about the taxonomy.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-n</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--unknowns</span></code></p></td>
<td><p>Set to include information about unknown bases (Ns).</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 15%" />
<col style="width: 21%" />
<col style="width: 64%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Utility</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-h</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--help</span></code></p></td>
<td><p>Prints help on command-line flag usage.</p></td>
</tr>
</tbody>
</table>
<p><strong>Usage:</strong></p>
<p>Use the <code class="docutils literal notranslate"><span class="pre">sdfstats</span></code> command to get information about the contents of
SDFs.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#format"><span class="std std-ref">format</span></a>,
<a class="reference internal" href="#sdf2fasta"><span class="std std-ref">sdf2fasta</span></a>,
<a class="reference internal" href="#sdf2fastq"><span class="std std-ref">sdf2fastq</span></a>,
<a class="reference internal" href="#sdfstats"><span class="std std-ref">sdfstats</span></a></p>
</div>
</div>
<div class="section" id="sdfsubset">
<h3>sdfsubset<a class="headerlink" href="#sdfsubset" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>Extracts a specified subset of sequences from one SDF and outputs them
to another SDF.</p>
<p><strong>Syntax:</strong></p>
<p>Individual specification of sequence ids:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg sdfsubset [OPTION]... -i SDF -o SDF STRING+
</pre></div>
</div>
<p>File list specification of sequence ids:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg sdfsubset [OPTION]... -i SDF -o SDF -I FILE
</pre></div>
</div>
<p><strong>Example:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg sdfsubset -i reads -o subset_reads 10 20 30 40 50
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<table class="docutils align-default">
<colgroup>
<col style="width: 16%" />
<col style="width: 33%" />
<col style="width: 51%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>File Input/Output</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-i</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--input=SDF</span></code></p></td>
<td><p>Specifies the input SDF.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-o</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--output=SDF</span></code></p></td>
<td><p>The name of the output SDF.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 6%" />
<col style="width: 13%" />
<col style="width: 81%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Filtering</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--end-id=INT</span></code></p></td>
<td><p>Only output sequences with sequence id less than the given number. (Sequence ids start at 0).</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--start-id=INT</span></code></p></td>
<td><p>Only output sequences with sequence id greater than or equal to the given number. (Sequence ids start at 0).</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-I</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--id-file=FILE</span></code></p></td>
<td><p>Name of a file containing a list of sequences to extract, one per line.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--names</span></code></p></td>
<td><p>Interpret any specified sequence as names instead of numeric sequence ids.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">STRING+</span></code></p></td>
<td><p>Specifies the sequence id, or sequence name if the names flag is set to extract from the input SDF. May be specified 0 or more times.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 15%" />
<col style="width: 21%" />
<col style="width: 64%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Utility</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-h</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--help</span></code></p></td>
<td><p>Prints help on command-line flag usage.</p></td>
</tr>
</tbody>
</table>
<p><strong>Usage:</strong></p>
<p>Use this command to obtain a subset of sequences from an SDF. Either
specify the subset on the command line as a list of space-separated
sequence ids or using the <code class="docutils literal notranslate"><span class="pre">--id-file</span></code> parameter to specify a file
containing a list of sequence ids, one per line. Sequence ids start from
zero and are the same as the ids that <code class="docutils literal notranslate"><span class="pre">map</span></code> uses by default in the
<code class="docutils literal notranslate"><span class="pre">QNAME</span></code> field of its BAM files.</p>
<p>For example:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg sdfsubset -i reads -o subset_reads 10 20 30 40 50
</pre></div>
</div>
<p>This will produce an SDF called subset_reads with sequences 10, 20, 30,
40 and 50 from the original SDF contained in it.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#sdfsubseq"><span class="std std-ref">sdfsubseq</span></a>,
<a class="reference internal" href="#sdfstats"><span class="std std-ref">sdfstats</span></a></p>
</div>
</div>
<div class="section" id="sdfsubseq">
<h3>sdfsubseq<a class="headerlink" href="#sdfsubseq" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>Prints a subsequence of a given sequence in an SDF.</p>
<p><strong>Syntax:</strong></p>
<p>Print sequences from sequence names:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg sdfsubseq [OPTION]... -i FILE STRING+
</pre></div>
</div>
<p>Print sequences from sequence ids:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg sdfsubseq [OPTION]... -i FILE -I STRING+
</pre></div>
</div>
<p><strong>Example:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg sdfsubseq -i reads -I 0:1+100
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<table class="docutils align-default">
<colgroup>
<col style="width: 17%" />
<col style="width: 34%" />
<col style="width: 48%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>File Input/Output</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-i</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--input=FILE</span></code></p></td>
<td><p>Specifies the input SDF.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 4%" />
<col style="width: 13%" />
<col style="width: 83%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Filtering</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-I</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--sequence-id</span></code></p></td>
<td><p>If set, use sequence id instead of sequence name in region (0-based)</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">REGION+</span></code></p></td>
<td><p>The range to display. The format is one of &lt;sequence_name&gt;, &lt;sequence_name&gt;:&lt;start&gt;-&lt;end&gt;, &lt;sequence_name&gt;:&lt;pos&gt;+&lt;length&gt; or &lt;sequence_name&gt;:&lt;pos&gt;~&lt;padding&gt;.
Must be specified 1 or more times.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 12%" />
<col style="width: 35%" />
<col style="width: 53%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Utility</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-f</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--fasta</span></code></p></td>
<td><p>Set to output in FASTA format.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-q</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--fastq</span></code></p></td>
<td><p>Set to output in FASTQ format.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-h</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--help</span></code></p></td>
<td><p>Prints help on command-line flag usage.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-r</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--reverse-complement</span></code></p></td>
<td><p>Set to output in reverse complement.</p></td>
</tr>
</tbody>
</table>
<p><strong>Usage:</strong></p>
<p>Prints out the nucleotides or amino acids of specified regions in a set
of sequences.</p>
<p>For example:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg sdfsubseq --input reads --sequence-id 0:1+20
AGGCGTCTGCAGCCGACGCG
</pre></div>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#sdfsubset"><span class="std std-ref">sdfsubset</span></a>,
<a class="reference internal" href="#sdfstats"><span class="std std-ref">sdfstats</span></a></p>
</div>
</div>
<div class="section" id="mendelian">
<h3>mendelian<a class="headerlink" href="#mendelian" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>The <code class="docutils literal notranslate"><span class="pre">mendelian</span></code> command checks a multi-sample VCF file for variant calls
which do not follow Mendelian inheritance, and compute aggregate sample
concordance.</p>
<p><strong>Syntax:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg mendelian [OPTION]... -i FILE -t SDF
</pre></div>
</div>
<p><strong>Example:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg mendelian -i family.vcf.gz -t genome_ref
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<table class="docutils align-default">
<colgroup>
<col style="width: 6%" />
<col style="width: 25%" />
<col style="width: 69%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>File Input/Output</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-i</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--input=FILE</span></code></p></td>
<td><p>VCF file containing multi-sample variant calls. Use ‘-‘ to read from standard input.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-o</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--output=FILE</span></code></p></td>
<td><p>If set, output annotated calls to this VCF file. Use ‘-‘ to write to standard output.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--output-consistent=FILE</span></code></p></td>
<td><p>If set, output only consistent calls to this VCF file.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--output-inconsistent=FILE</span></code></p></td>
<td><p>If set, output only non-Mendelian calls to this VCF file.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-t</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--template=SDF</span></code></p></td>
<td><p>SDF containing the reference genome.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 5%" />
<col style="width: 21%" />
<col style="width: 74%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Sensitivity Tuning</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--all-records</span></code></p></td>
<td><p>Use all records, regardless of filters (Default is to only process records where FILTER is <code class="docutils literal notranslate"><span class="pre">.</span></code> or <code class="docutils literal notranslate"><span class="pre">PASS</span></code>)</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-l</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--lenient</span></code></p></td>
<td><p>Allow homozygous diploid calls in place of haploid calls and assume missing values are equal to the reference.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--min-concordance=FLOAT</span></code></p></td>
<td><p>Percentage concordance required for consistent parentage (Default is 99.0)</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--pedigree=FILE</span></code></p></td>
<td><p>Genome relationships PED file (Default is to extract pedigree information from VCF header fields)</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 6%" />
<col style="width: 23%" />
<col style="width: 72%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Utility</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-h</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--help</span></code></p></td>
<td><p>Print help on command-line flag usage.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-Z</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-gzip</span></code></p></td>
<td><p>Do not gzip the output.</p></td>
</tr>
</tbody>
</table>
<p><strong>Usage:</strong></p>
<p>Given a multi-sample VCF file for a nuclear family with a defined
pedigree, the <code class="docutils literal notranslate"><span class="pre">mendelian</span></code> command examines the variant calls and outputs
the number of violations of Mendelian inheritance. If the
<code class="docutils literal notranslate"><span class="pre">--output-inconsistent</span></code> parameter is set, all detected violations are
written into an output VCF file. As such, this command may be regarded
as a VCF filter, outputting those variant calls needing a non-Mendelian
explanation. Such calls may be the consequence of sequencing error,
calling on low-coverage, or genuine novel variants in one or more
individuals.</p>
<p>Pedigree information regarding the relationships between samples and the
sex of each sample is extracted from the VCF headers automatically
created by the RTG pedigree-aware variant calling commands. If this
pedigree information is absent from the VCF header or is incorrect, a
pedigree file can be explicitly supplied with the <code class="docutils literal notranslate"><span class="pre">--pedigree</span></code> flag.</p>
<p>To ensure correct behavior when dealing with sex chromosomes it is
necessary to specify a sex-aware reference and ensure the sex of each
sample is supplied as part of the pedigree information. While it is best
to give the reference SDF used in the creation of the VCF, for checking
third-party outputs any reference SDF containing the same chromosome
names and an appropriate <code class="docutils literal notranslate"><span class="pre">reference.txt</span></code> file will work. For more
information, see <a class="reference internal" href="appendix.html#rtg-reference-file-format"><span class="std std-ref">RTG reference file format</span></a>. Variants calls where
the call ploidy does not match what is expected are annotated in the
output VCF with an <code class="docutils literal notranslate"><span class="pre">MCP</span></code> FORMAT annotation.</p>
<p>Particularly when evaluating VCF files that have been produced by third
party tools or when the VCF is the result of combining independent
per-sample calling, it is common to end up with situations where calls
are not available for every member of the family. Under normal
circumstances <code class="docutils literal notranslate"><span class="pre">mendelian</span></code> will attempt to determine Mendelian
consistency on the basis of the values that have been provided. Records
where the presence of missing values makes the Mendelian consistency
undecidable contain <code class="docutils literal notranslate"><span class="pre">MCU</span></code> INFO annotations in the annotated output
VCF. The following examples illustrate some consistent, undecidable, and
inconsistent calls in the presence of missing values:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>CHROM  FATHER_GT  MOTHER_GT  SON_GT  STATUS
chrX   .          0/1        1       OK
chr1   ./.        1/1        1/2     MCU
chr1   ./.        1/1        2/2     MCV
</pre></div>
</div>
<p>Since the number of calls where one sample is missing can be quite high,
an alternative option is to treat missing values as equal to the
reference by using the <code class="docutils literal notranslate"><span class="pre">--lenient</span></code> parameter. Note that while this
approach will be correct in most cases, it will give inaccurate results
where the calling between different samples has reported the variant in
an equivalent but slightly different position or representation
(e.g. positioning of indels within homopolymer regions, differences of
representation such as splitting MNPs into multiple SNPs etc).</p>
<p>The <code class="docutils literal notranslate"><span class="pre">mendelian</span></code> command computes overall concordance between related
samples to assist detecting cases where pedigree has been incorrectly
recorded or samples have been mislabeled. For each child in the
pedigree, pairwise concordance is computed with respect to each parent
by identifying diploid calls where the parent does not contain either
allele called in the child. Low pairwise concordance with a single
parent may indicate that the parent is the source of the problem,
whereas low pairwise concordance with both parents may indicate that the
child is the source of the problem. A stricter three-way concordance is
also recorded.</p>
<p>By default, only VCF records with the <code class="docutils literal notranslate"><span class="pre">FILTER</span></code> field set to PASS or
missing are processed. All variant records can be examined by specifying
the <code class="docutils literal notranslate"><span class="pre">--all-records</span></code> parameter.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#family"><span class="std std-ref">family</span></a>,
<a class="reference internal" href="#population"><span class="std std-ref">population</span></a>,
<a class="reference internal" href="#vcfstats"><span class="std std-ref">vcfstats</span></a></p>
</div>
</div>
<div class="section" id="vcfannotate">
<h3>vcfannotate<a class="headerlink" href="#vcfannotate" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>Used to add annotations to a VCF file, either to the VCF <code class="docutils literal notranslate"><span class="pre">ID</span></code> field,
as a VCF <code class="docutils literal notranslate"><span class="pre">INFO</span></code> sub-field, or as a VCF <code class="docutils literal notranslate"><span class="pre">FORMAT</span></code> sub-field.</p>
<p><strong>Syntax:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg vcfannotate [OPTION]... -b FILE -i FILE -o FILE
</pre></div>
</div>
<p><strong>Example:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg vcfannotate -b dbsnp.bed -i snps.vcf.gz -o snps-dbsnp.vcf.gz
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<table class="docutils align-default">
<colgroup>
<col style="width: 4%" />
<col style="width: 15%" />
<col style="width: 81%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>File Input/Output</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--bed-regions=FILE</span></code></p></td>
<td><p>If set, only read VCF records that overlap the ranges contained in the specified BED file.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-i</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--input=FILE</span></code></p></td>
<td><p>VCF file containing variants to annotate. Use ‘-‘ to read from standard input.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-o</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--output=FILE</span></code></p></td>
<td><p>Output VCF file name. Use ‘-‘ to write to standard output.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--region=REGION</span></code></p></td>
<td><p>If set, only read VCF records within the specified range. The format is one of &lt;sequence_name&gt;, &lt;sequence_name&gt;:&lt;start&gt;-&lt;end&gt;, &lt;sequence_name&gt;:&lt;pos&gt;+&lt;length&gt; or
&lt;sequence_name&gt;:&lt;pos&gt;~&lt;padding&gt;</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 4%" />
<col style="width: 15%" />
<col style="width: 81%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Reporting</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-A</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--annotation=STRING</span></code></p></td>
<td><p>Add computed annotation to VCF records. Allowed values are [AC, AN, EP, GQD, IC, LAL, MEANQAD, NAA, PD, QA, QD, RA, SCONT, VAF, VAF1, ZY]. May be specified 0 or
more times, or as a comma separated list.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--bed-ids=FILE</span></code></p></td>
<td><p>Add variant IDs from BED file. May be specified 0 or more times.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--bed-info=FILE</span></code></p></td>
<td><p>Add INFO annotations from BED file. May be specified 0 or more times.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--fill-an-ac</span></code></p></td>
<td><p>Add or update the AN and AC INFO fields.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--info-description=STRING</span></code></p></td>
<td><p>If the BED INFO field is not already declared, use this description in the header (Default is Annotation)</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--info-id=STRING</span></code></p></td>
<td><p>The INFO ID for BED INFO annotations (Default is ANN)</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--relabel=FILE</span></code></p></td>
<td><p>Relabel samples according to <code class="docutils literal notranslate"><span class="pre">old-name</span> <span class="pre">new-name</span></code> pairs in specified file.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--vcf-ids=FILE</span></code></p></td>
<td><p>Add variant IDs from VCF file. May be specified 0 or more times.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 6%" />
<col style="width: 22%" />
<col style="width: 72%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Utility</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-a</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--add-header=STRING|FILE</span></code></p></td>
<td><p>File containing VCF header lines to add, or a literal header line. May be specified 0 or more times.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-h</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--help</span></code></p></td>
<td><p>Print help on command-line flag usage.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-Z</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-gzip</span></code></p></td>
<td><p>Do not gzip the output.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-header</span></code></p></td>
<td><p>Prevent VCF header from being written.</p></td>
</tr>
</tbody>
</table>
<p><strong>Usage:</strong></p>
<p>Use <code class="docutils literal notranslate"><span class="pre">vcfannotate</span></code> to add text annotations to variants.</p>
<p>A common use case is to add annotations to only those variants that fall
within ranges specified in a BED or VCF file, supplied via <code class="docutils literal notranslate"><span class="pre">--bed-ids</span></code>
or <code class="docutils literal notranslate"><span class="pre">--vcf-ids</span></code> respectively.  The annotations from the BED file are
added as an <code class="docutils literal notranslate"><span class="pre">INFO</span></code> field in the output VCF file. It can also be used
to compute or fill in certain additional annotations from the existing
content. Note that this annotation method is solely based on the
position and span of the variant, ignoring actual alleles and genotypes.</p>
<p>If the <code class="docutils literal notranslate"><span class="pre">--bed-ids</span></code> flag is used, instead of adding the annotation to the
<code class="docutils literal notranslate"><span class="pre">INFO</span></code> fields, it is added to the <code class="docutils literal notranslate"><span class="pre">ID</span></code> column of the VCF file instead.
If the <code class="docutils literal notranslate"><span class="pre">--vcf-ids</span></code> flag is used, the <code class="docutils literal notranslate"><span class="pre">ID</span></code> column of the input VCF file
is used to update the <code class="docutils literal notranslate"><span class="pre">ID</span></code> column of the output VCF file instead.</p>
<p>If the <code class="docutils literal notranslate"><span class="pre">--fill-an-ac</span></code> flag is set, the output VCF will have the <code class="docutils literal notranslate"><span class="pre">AN</span></code> and
<code class="docutils literal notranslate"><span class="pre">AC</span></code> info fields (as defined in the VCF 4.2 specification) created or
updated.</p>
<p>It is also possible to use <code class="docutils literal notranslate"><span class="pre">vcfannotate</span></code> to insert additional VCF
header lines into the VCF header. These are supplied using the
<code class="docutils literal notranslate"><span class="pre">--add-header</span></code> flag which may either be a literal VCF header line
(useful for adding one or two header lines), or from a file.</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg vcfannotate -i in.vcf.gz -o out.vcf.gz \
--add-header &quot;##SAMPLE=&lt;ID=NA24385,Sex=MALE&gt;&quot; \
--add-header &quot;##SAMPLE=&lt;ID=NA24143,Sex=FEMALE&gt;&quot; \
--add-header &quot;##SAMPLE=&lt;ID=NA24149,Sex=MALE&gt;&quot; \
--add-header &quot;##PEDIGREE=&lt;Child=NA24385,Mother=NA24143,Father=NA24149&gt;&quot;
</pre></div>
</div>
<p>or alternatively:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg vcfannotate -i in.vcf.gz -o out.vcf.gz --add-header ped_vcf_headers.txt
</pre></div>
</div>
<p>Care should be taken that the lines being inserted are valid VCF header lines.</p>
<p>If the <code class="docutils literal notranslate"><span class="pre">--annotation</span></code> flag is set, <code class="docutils literal notranslate"><span class="pre">vcfannotate</span></code> attempts to compute
the specified annotation(s) and add them as <code class="docutils literal notranslate"><span class="pre">FORMAT</span></code> fields in the
corresponding records.  Records for which particular annotations cannot be
computed, due to a lack of pre-requisite fields, will not be modified.</p>
<p>For a description of the meaning of fields available for annotation,
see <a class="reference internal" href="appendix.html#small-variant-vcf-output-file-description"><span class="std std-ref">Small-variant VCF output file description</span></a>. The <code class="docutils literal notranslate"><span class="pre">SCONT</span></code>
annotation is a convenience to annotate with all of the contrary
evidence annotations: <code class="docutils literal notranslate"><span class="pre">DCOC</span></code>, <code class="docutils literal notranslate"><span class="pre">DCOF</span></code>, <code class="docutils literal notranslate"><span class="pre">OCOC</span></code>, <code class="docutils literal notranslate"><span class="pre">OCOF</span></code>.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#snp"><span class="std std-ref">snp</span></a>,
<a class="reference internal" href="#family"><span class="std std-ref">family</span></a>,
<a class="reference internal" href="#somatic"><span class="std std-ref">somatic</span></a>,
<a class="reference internal" href="#population"><span class="std std-ref">population</span></a>,
<a class="reference internal" href="#vcffilter"><span class="std std-ref">vcffilter</span></a>,
<a class="reference internal" href="#vcfsubset"><span class="std std-ref">vcfsubset</span></a></p>
</div>
</div>
<div class="section" id="vcfdecompose">
<h3>vcfdecompose<a class="headerlink" href="#vcfdecompose" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>Decomposes complex variants within a VCF file into smaller components.</p>
<p><strong>Syntax:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg vcfdecompose [OPTION]... -i FILE -o FILE
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<table class="docutils align-default">
<colgroup>
<col style="width: 7%" />
<col style="width: 18%" />
<col style="width: 75%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>File Input/Output</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-i</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--input=FILE</span></code></p></td>
<td><p>VCF file containing variants to decompose. Use ‘-‘ to read from standard input.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-o</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--output=FILE</span></code></p></td>
<td><p>Output VCF file name. Use ‘-‘ to write to standard output.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-t</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--template=SDF</span></code></p></td>
<td><p>SDF of the reference genome the variants are called against.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 7%" />
<col style="width: 18%" />
<col style="width: 75%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Sensitivity Tuning</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--break-indels</span></code></p></td>
<td><p>If set, peel as many SNPs off an indel as possible.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--break-mnps</span></code></p></td>
<td><p>If set, break MNPs into individual SNPs.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 7%" />
<col style="width: 18%" />
<col style="width: 75%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Utility</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-h</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--help</span></code></p></td>
<td><p>Print help on command-line flag usage.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-Z</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-gzip</span></code></p></td>
<td><p>Do not gzip the output.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-header</span></code></p></td>
<td><p>Prevent VCF header from being written.</p></td>
</tr>
</tbody>
</table>
<p><strong>Usage:</strong></p>
<p>The <code class="docutils literal notranslate"><span class="pre">vcfdecompose</span></code> command decomposes and trims variants based on
a multiple sequence alignment between the alleles in each VCF
record. Only records where every ALT allele is an ordinary allele
(i.e. consisting of nucleotides) will undergo decomposition. In
addition, if there are redundant same-as-reference bases in the alleles,
these will be trimmed off.</p>
<p>The default behavior is to break the variant at positions where there
is at least one base aligned to the reference across all ALT alleles, so
the output may contain MNPs or impure indels. If desired, MNPs can be
split into individual SNPs via <code class="docutils literal notranslate"><span class="pre">--break-mnps</span></code>. Similarly, impure
indels can be split into a combination of SNPs and pure indels via
<code class="docutils literal notranslate"><span class="pre">--break-indels</span></code>.</p>
<p>Although decomposed variants carry through the original <code class="docutils literal notranslate"><span class="pre">INFO</span></code> and
<code class="docutils literal notranslate"><span class="pre">FORMAT</span></code> annotations, the decomposition may mean that some annotations
are no longer semantically correct.  In particular, any VCF <code class="docutils literal notranslate"><span class="pre">FORMAT</span></code>
fields declared to be of type <code class="docutils literal notranslate"><span class="pre">A</span></code>, <code class="docutils literal notranslate"><span class="pre">G</span></code>, or <code class="docutils literal notranslate"><span class="pre">R</span></code> will no longer be
valid if the set of alleles has changed.</p>
<p>Note that the reference genome is an optional parameter. When variants
are decomposed and trimmed, the resulting variant may require a padding
base to be added, as required by the VCF specification. The VCF
specification suggests that the padding base should be the base before
the variant (i.e. padding on the left), but sometimes this requires
knowledge of reference bases not present in the original record.  When
the reference genome is supplied, <code class="docutils literal notranslate"><span class="pre">vcfdecompose</span></code> will ensure that any
padding bases are added on the left of the variant. If the reference
genome is not supplied, padding bases may sometimes be on the right hand
side of the variant. For example:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>1  20  .  GCGCGCGCGCG  TTTGCGCGCTTGCGCGTTT  .  PASS  .              GT  1/0
</pre></div>
</div>
<p>will decompose without a reference genome as:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>1  20  .  G            TTTG                 .  PASS  ORP=20;ORL=11  GT  1/0
1  25  .  C            CTT                  .  PASS  ORP=20;ORL=11  GT  1/0
</pre></div>
</div>
<p>and with a reference genome (where the reference base at position 19 can
be determined to be a <code class="docutils literal notranslate"><span class="pre">T</span></code>) as:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>1  19  .  T            TTTT                 .  PASS  ORP=20;ORL=11  GT  1/0
1  25  .  C            CTT                  .  PASS  ORP=20;ORL=11  GT  1/0
</pre></div>
</div>
<p>The variants that are left vs right-padded are equivalent and identified
as such by haplotype-aware comparison tools such as <code class="docutils literal notranslate"><span class="pre">vcfeval</span></code>.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#vcffilter"><span class="std std-ref">vcffilter</span></a>,
<a class="reference internal" href="#vcfeval"><span class="std std-ref">vcfeval</span></a></p>
</div>
</div>
<div class="section" id="vcfeval">
<h3>vcfeval<a class="headerlink" href="#vcfeval" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>Evaluates called variants for agreement with a baseline variant set
irrespective of representational differences. Outputs a weighted ROC
file which can be viewed with <code class="docutils literal notranslate"><span class="pre">rtg</span> <span class="pre">rocplot</span></code> and VCF files containing false
positives (called variants not matched in the baseline), false negatives
(baseline variants not matched in the call set), and true positives
(variants that match between the baseline and calls).</p>
<p>The baseline variants might be the variants that were used to generate a
synthetic simulated sample (such as via <code class="docutils literal notranslate"><span class="pre">popsim</span></code>, <code class="docutils literal notranslate"><span class="pre">samplesim</span></code>, etc),
a gold-standard VCF corresponding to a reference sample such as NA12878,
or simply an alternative call-set being used as a basis for comparison.</p>
<p><strong>Syntax:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg vcfeval [OPTION]... -b FILE -c FILE -o DIR -t SDF
</pre></div>
</div>
<p><strong>Example:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg vcfeval -b goldstandard.vcf.gz -c snps.vcf.gz -t HUMAN_reference \
  --sample daughter -f AVR -o eval
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<table class="docutils align-default">
<colgroup>
<col style="width: 4%" />
<col style="width: 15%" />
<col style="width: 81%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>File Input/Output</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-b</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--baseline=FILE</span></code></p></td>
<td><p>VCF file containing baseline variants.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--bed-regions=FILE</span></code></p></td>
<td><p>If set, only read VCF records that overlap the ranges contained in the specified BED file.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-c</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--calls=FILE</span></code></p></td>
<td><p>VCF file containing called variants.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-e</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--evaluation-regions=FILE</span></code></p></td>
<td><p>If set, evaluate within regions contained in the supplied BED file, allowing transborder matches. To be used for truth-set high-confidence regions or other
regions of interest where region boundary effects should be minimized.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-o</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--output=DIR</span></code></p></td>
<td><p>Directory for output.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--region=REGION</span></code></p></td>
<td><p>If set, only read VCF records within the specified range. The format is one of &lt;sequence_name&gt;, &lt;sequence_name&gt;:&lt;start&gt;-&lt;end&gt;, &lt;sequence_name&gt;:&lt;pos&gt;+&lt;length&gt; or
&lt;sequence_name&gt;:&lt;pos&gt;~&lt;padding&gt;</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-t</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--template=SDF</span></code></p></td>
<td><p>SDF of the reference genome the variants are called against.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 4%" />
<col style="width: 15%" />
<col style="width: 81%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Filtering</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--all-records</span></code></p></td>
<td><p>Use all records regardless of FILTER status (Default is to only process records where FILTER is <code class="docutils literal notranslate"><span class="pre">.</span></code> or <code class="docutils literal notranslate"><span class="pre">PASS</span></code>)</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--decompose</span></code></p></td>
<td><p>Decompose complex variants into smaller constituents to allow partial credit.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--ref-overlap</span></code></p></td>
<td><p>Allow alleles to overlap where bases of either allele are same-as-ref (Default is to only allow VCF anchor base overlap)</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--sample=STRING</span></code></p></td>
<td><p>The name of the sample to select. Use &lt;baseline_sample&gt;,&lt;calls_sample&gt; to select different sample names for baseline and calls. (Required when using
multi-sample VCF files)</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--sample-ploidy=INT</span></code></p></td>
<td><p>Expected ploidy of samples (Default is 2)</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--squash-ploidy</span></code></p></td>
<td><p>Treat heterozygous genotypes as homozygous ALT in both baseline and calls, to allow matches that ignore zygosity differences.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 4%" />
<col style="width: 15%" />
<col style="width: 81%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Reporting</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--at-precision=FLOAT</span></code></p></td>
<td><p>Output summary statistics where precision &gt;= supplied value (Default is to summarize at maximum F-measure)</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--at-sensitivity=FLOAT</span></code></p></td>
<td><p>Output summary statistics where sensitivity &gt;= supplied value (Default is to summarize at maximum F-measure)</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-roc</span></code></p></td>
<td><p>Do not produce ROCs.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-m</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--output-mode=STRING</span></code></p></td>
<td><p>Output reporting mode. Allowed values are [split, annotate, combine, ga4gh, roc-only] (Default is split)</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--roc-expr=STRING</span></code></p></td>
<td><p>Output ROC file for variants matching custom JavaScript expression. Use the form &lt;LABEL&gt;=&lt;EXPRESSION&gt;. May be specified 0 or more times.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--roc-regions=STRING</span></code></p></td>
<td><p>Output ROC file for variants overlapping custom regions supplied in BED file. Use the form &lt;LABEL&gt;=&lt;FILENAME&gt;. May be specified 0 or more times.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--roc-subset=STRING</span></code></p></td>
<td><p>Output ROC file for preset variant subset. Allowed values are [hom, het, snp, non-snp, mnp, indel]. May be specified 0 or more times, or as a comma separated
list.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-O</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--sort-order=STRING</span></code></p></td>
<td><p>The order in which to sort the ROC scores so that <code class="docutils literal notranslate"><span class="pre">good</span></code> scores come before <code class="docutils literal notranslate"><span class="pre">bad</span></code> scores. Allowed values are [ascending, descending] (Default is descending)</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-f</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--vcf-score-field=STRING</span></code></p></td>
<td><p>The name of the VCF FORMAT field to use as the ROC score. Also valid are <code class="docutils literal notranslate"><span class="pre">QUAL</span></code>, <code class="docutils literal notranslate"><span class="pre">INFO.&lt;name&gt;</span></code> or <code class="docutils literal notranslate"><span class="pre">FORMAT.&lt;name&gt;</span></code> to select the named VCF FORMAT or INFO
field (Default is GQ)</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 7%" />
<col style="width: 26%" />
<col style="width: 68%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Utility</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-h</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--help</span></code></p></td>
<td><p>Print help on command-line flag usage.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-Z</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-gzip</span></code></p></td>
<td><p>Do not gzip the output.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-T</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--threads=INT</span></code></p></td>
<td><p>Number of threads (Default is the number of available cores)</p></td>
</tr>
</tbody>
</table>
<p><strong>Usage:</strong></p>
<p>The <code class="docutils literal notranslate"><span class="pre">vcfeval</span></code> command can be used to generate VCF files containing
called variants that were in the baseline VCF, called variants that were
not in the baseline VCF and baseline variants that were not in the
called variants. It also produces ROC curve data files based on a score
contained in a VCF field which show the predictive power of that field
for the quality of the variant calls.</p>
<p>When developing and validating sequencing pipelines and variant calling
algorithms, the comparison of variant call sets is a common problem. The
naïve way of computing these numbers is to look at the same reference
locations in the baseline (ground truth) and called variant set, and see
if genotype calls match at the same position. However, a complication
arises due to possible differences in representation for indels between
the baseline and the call sets within repeats or homopolymers, and in
multiple-nucleotide polymorphisms (MNPs), which encompass several nearby
nucleotides and are locally phased. The <code class="docutils literal notranslate"><span class="pre">vcfeval</span></code> command includes a
novel dynamic-programming algorithm for comparing variant call sets that
deals with complex call representation discrepancies, and minimizes
false positives and negatives across the entire call sets for accurate
performance evaluation. A primary advantage of <code class="docutils literal notranslate"><span class="pre">vcfeval</span></code> (compared to
other tools) is that the evaluation does not depend on normalization or
decomposition, and so the results of analysis can easily be used to
relate to the original variant calls and their annotations.</p>
<p>Note that <code class="docutils literal notranslate"><span class="pre">vcfeval</span></code> operates at the level of local haplotypes for a
sample, so for a diploid genotype, both alleles must match in order to
be considered correct. Some of the vcfeval output modes (described
below) automatically perform an additional haploid analysis phase to
identify variants which may not have a diploid match but which share a
common allele (for example, zygosity errors made during calling). If
desired, this more lenient haploid comparison can be used at the outset
by setting the <code class="docutils literal notranslate"><span class="pre">--squash-ploidy</span></code> flag (see below).</p>
<p>Note that variants selected for inclusion in a haplotype cannot be
permitted to overlap each other (otherwise the question arises of which
variant should have priority when determining the resulting haplotype),
and any well-formed call-set should not contain these situations in
order to avoid such ambiguity. When such cases are encountered by
<code class="docutils literal notranslate"><span class="pre">vcfeval</span></code>, the best non-overlapping result is determined. A special case
of overlapping variants is where calls are denoted as partially the same
as the reference (for example, a typical heterozygous call). Strictly
speaking such variants are an assertion that the relevant haplotype
bases must not be altered from the reference and overlap should not be
permitted (this is the interpretation that <code class="docutils literal notranslate"><span class="pre">vcfeval</span></code> employs by
default). However, sometimes as a result of using non-haplotype-aware
variant calling tools or when using naïve merging of multiple call sets,
a more lenient comparison is desired. The <code class="docutils literal notranslate"><span class="pre">--ref-overlap</span></code> flag will
permit such overlapping variants to both match, as long as any overlap
only occurs where one variant or other has asserted haplotype bases as
being the same as reference.</p>
<div class="section" id="common-allele-matching-with-squash-ploidy">
<h4>Common allele matching with <code class="docutils literal notranslate"><span class="pre">--squash-ploidy</span></code><a class="headerlink" href="#common-allele-matching-with-squash-ploidy" title="Permalink to this headline">¶</a></h4>
<p>When <code class="docutils literal notranslate"><span class="pre">--squash-ploidy</span></code> is specified, a haploid match is attempted
using <em>each</em> of the non-reference alleles used in the sample
genotype. For example if the baseline and call VCFs each had a record
with the same REF and ALT alleles declared, the following GT fields
would be considered a match:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>0/1, 1/1, 1/2   (genotypes match due to the 1 allele)
0/2, 1/2, 2/2   (genotypes match due to the 2 allele)
</pre></div>
</div>
<p>Thus <code class="docutils literal notranslate"><span class="pre">--squash-ploidy</span></code> matches any case where the baseline and calls
share a common allele.  This is most often used to run matching that
does not penalize for genotyping errors. For example, it is recommended
to use this option when matching somatic variant calls, as since somatic
variation is usually associated with variable allelic fractions and
heterogeneity that mean strict diploid genotype comparisons are not
appropriate.</p>
</div>
<div class="section" id="comparing-non-diploid-genomes">
<h4>Comparing non-diploid genomes<a class="headerlink" href="#comparing-non-diploid-genomes" title="Permalink to this headline">¶</a></h4>
<p>By default, <code class="docutils literal notranslate"><span class="pre">vcfeval</span></code> assumes diploid organisms (that is, the expected
ploidy of any GT call is 2). As a special case to ease the comparison of
male calls on sex chromosomes (where callers often continue to use
diploid representation), haploid calls are treated as homozygous
diploid. Any calls made with unexpected ploidy are ignored and reported
in the <code class="docutils literal notranslate"><span class="pre">vcfeval</span></code> log file.</p>
<p>To compare genomes with non-diploid ploidy, the expected sample ploidy
can be overridden via <code class="docutils literal notranslate"><span class="pre">--sample-ploidy</span></code> – for example
<code class="docutils literal notranslate"><span class="pre">--sample-ploidy=4</span></code> would be used to compare tetraploid organisms.</p>
</div>
<div class="section" id="comparing-with-a-vcf-that-has-no-sample-column">
<h4>Comparing with a VCF that has no sample column<a class="headerlink" href="#comparing-with-a-vcf-that-has-no-sample-column" title="Permalink to this headline">¶</a></h4>
<p>A common scenario is to match a call set against a baseline which
contains no sample column, where the objective is to identify which
baseline alleles which have been called. One example of this is to
identify whether calls match a database of known high-priority somatic
variants such as COSMIC, or to find calls which have been previously
seen in a population allele database such as ExAC. Ordinarily
<code class="docutils literal notranslate"><span class="pre">vcfeval</span></code> requires the input VCFs to contain a sample column
containing a genotype in the GT field, however, it is possible to
specify a special sample name of ‘ALT’ in order to indicate that the
the genotypes for comparison should be derived from the ALT alleles of
the record. This can be specified independently for baseline and calls,
for example:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg vcfeval -t build37.sdf -b cosmic.vcf.gz -c tumor-calls.vcf.gz \
--squash-ploidy --sample ALT,tumor -o tumor-vs-cosmic
</pre></div>
</div>
<p>Which would perform a haploid matching of the GT of the called sample
‘tumor’ against all possible haploid genotypes in the COSMIC VCF. The
resulting true positives file contains all the calls containing an
allele present in the COSMIC VCF.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>It is also possible to run a diploid comparison by omitting
<code class="docutils literal notranslate"><span class="pre">--squash-ploidy</span></code>, but this is not usually required, and is
computationally more intensive since there may be many more possible
diploid genotypes to explore, particularly if the ALT VCF contains
many multiallelic records.)</p>
</div>
</div>
<div class="section" id="evaluation-with-respect-to-regions">
<h4>Evaluation with respect to regions<a class="headerlink" href="#evaluation-with-respect-to-regions" title="Permalink to this headline">¶</a></h4>
<p>When evaluating exome variant calls, it may be useful to restrict
analysis only to exome target regions.  In this case, supply a BED file
containing the list of regions to restrict analysis to via the
<code class="docutils literal notranslate"><span class="pre">--bed-regions</span></code> flag. For a quick way to restrict analysis only to a
single region, the <code class="docutils literal notranslate"><span class="pre">--region</span></code> flag is also accepted. Note that when
restricting analysis to regions, there may be variants which can not be
correctly evaluated near the borders of each analysis region, if
determination of equivalence would require inclusion of variants outside
of the region. For this reason, it is recommended that such regions be
relatively inclusive.</p>
<p>When matching against gold standard truth sets which have an
accompanying high-confidence regions BED file, the flag
<code class="docutils literal notranslate"><span class="pre">--evaluation-regions</span></code> should be used instead of <code class="docutils literal notranslate"><span class="pre">--bed-regions</span></code>, as
it has special matching semantics that aims to reduce comparison region
boundary effects. When this comparison method is used, call variants
which match a baseline variant are only considered a true positive if
the baseline variant is inside the high confidence regions, and call
variants are only considered false positive if they fall inside the high
confidence regions.</p>
</div>
<div class="section" id="vcfeval-outputs">
<h4>vcfeval outputs<a class="headerlink" href="#vcfeval-outputs" title="Permalink to this headline">¶</a></h4>
<p>The primary outputs of <code class="docutils literal notranslate"><span class="pre">vcfeval</span></code> are VCF files indicating which variants
matched between the baseline and the calls VCF, and data files
containing information used to generate ROC curves with the <code class="docutils literal notranslate"><span class="pre">rocplot</span></code>
command (or via spreadsheet). <code class="docutils literal notranslate"><span class="pre">vcfeval</span></code> supports different VCF
output modes which can be selected with the <code class="docutils literal notranslate"><span class="pre">--output-mode</span></code> flag
according to the type of analysis workflow desired. The following modes
are available:</p>
<div class="section" id="split-output-mode-split">
<h5>Split (<code class="docutils literal notranslate"><span class="pre">--output-mode=split</span></code>)<a class="headerlink" href="#split-output-mode-split" title="Permalink to this headline">¶</a></h5>
<p>This output mode is the default, and produces separate VCF files for
each of the match categories. The individual VCF records in these files
are not altered in any way, preserving all annotations present in the
input files.</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">tp.vcf</span></code> – contains those variants from the <em>calls</em> VCF which agree
with variants in the baseline VCF</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">tp-baseline.vcf</span></code> – contains those variants from the <em>baseline</em> VCF
which agree with variants in the calls VCF. Thus, the variants in
<code class="docutils literal notranslate"><span class="pre">tp.vcf</span></code> and <code class="docutils literal notranslate"><span class="pre">tp-baseline.vcf</span></code> are equivalent. This file can be used
to successively refine a highly sensitive baseline variant set to
produce a consensus from several call sets.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">fp.vcf</span></code> – contains variants from the <em>calls</em> VCF which do not agree
with baseline variants.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">fn.vcf</span></code> – contains variants from the <em>baseline</em> VCF which were not
correctly called.</p></li>
</ul>
<p>This mode performs a single pass comparison, either in diploid mode (the
default), or haploid mode (if <code class="docutils literal notranslate"><span class="pre">--squash-ploidy</span></code> has been set). The
separate output files produced by this mode allow the use of <code class="docutils literal notranslate"><span class="pre">vcfeval</span></code>
as an advanced haplotype-aware VCF intersection tool.</p>
</div>
<div class="section" id="annotate-output-mode-annotate">
<h5>Annotate (<code class="docutils literal notranslate"><span class="pre">--output-mode=annotate</span></code>)<a class="headerlink" href="#annotate-output-mode-annotate" title="Permalink to this headline">¶</a></h5>
<p>This output mode does not split the input VCFs by match status, but
instead adds <code class="docutils literal notranslate"><span class="pre">INFO</span></code> annotations containing the match status of each
record:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">calls.vcf</span></code> – contains variants from the <em>calls</em> VCF, augmented with
match status annotations.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">baseline.vcf</span></code> – contains variants from the <em>baseline</em> VCF, augmented
with match status annotations.</p></li>
</ul>
<p>This output mode automatically performs two comparison passes, the first
finds diploid matches (assigned a match status of <code class="docutils literal notranslate"><span class="pre">TP</span></code>), and a second
pass that applies a haploid mode to the false positives and false
negatives in order to find calls (such as zygosity errors) that contain
a common allele. This second category of match are annotated with status
<code class="docutils literal notranslate"><span class="pre">FN_CA</span></code> or <code class="docutils literal notranslate"><span class="pre">FP_CA</span></code> in the output VCFs, and those calls which do not
have any match are assigned status <code class="docutils literal notranslate"><span class="pre">FN</span></code> or <code class="docutils literal notranslate"><span class="pre">FP</span></code>. A status value of
<code class="docutils literal notranslate"><span class="pre">IGN</span></code> indicates a VCF record which was ignored (for example, due to
having a non-PASS filter status, representing a structural variant, or
otherwise containing a non-variant genotype). A status of <code class="docutils literal notranslate"><span class="pre">OUT</span></code>
indicates a VCF record which does not contain a match status due to
falling outside the evaluation regions when <code class="docutils literal notranslate"><span class="pre">--evaluation-regions</span></code> is
being used. The annotated VCF files produced in this mode may also be
used with <code class="docutils literal notranslate"><span class="pre">vcf2rocplot</span></code> to produce additional post-evaluation ROC data
files.</p>
</div>
<div class="section" id="combine-output-mode-combine">
<h5>Combine (<code class="docutils literal notranslate"><span class="pre">--output-mode=combine</span></code>)<a class="headerlink" href="#combine-output-mode-combine" title="Permalink to this headline">¶</a></h5>
<p>This output mode provides an easy way to view the baseline and call
variants in a single two-sample VCF.</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">output.vcf</span></code> – contains variants from both the <em>baseline</em> and <em>calls</em>
VCFs, augmented with match status annotations. The sample under
comparison from each of the input VCFs is extracted as a column in
the output. As the VCF records from the baseline and calls typically
have very different input annotations which can be difficult to
merge, and to keep the output format simple, there is no attempt to
preserve any of the original variant annotations.</p></li>
</ul>
<p>As with the annotation output mode, this output mode automatically
performs two comparison passes to find both diploid matches and haploid
(lenient) matches.</p>
</div>
<div class="section" id="roc-only-output-mode-roc-only">
<h5>ROC-only (<code class="docutils literal notranslate"><span class="pre">--output-mode=roc-only</span></code>)<a class="headerlink" href="#roc-only-output-mode-roc-only" title="Permalink to this headline">¶</a></h5>
<p>This output mode provides a lightweight way to run performance
benchmarking, as VCF file output is omitted, and only ROC data files are
produced.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>In addition, <code class="docutils literal notranslate"><span class="pre">vcfeval</span></code> has an output mode
(<code class="docutils literal notranslate"><span class="pre">--output-mode=ga4gh</span></code>) which produces the intermediate evaluation
format defined by the GA4GH Benchmarking Team, without additional
statistics files. This mode is not generally intended for end users,
rather it is used when <code class="docutils literal notranslate"><span class="pre">vcfeval</span></code> is selected as the comparison engine
inside the <code class="docutils literal notranslate"><span class="pre">hap.py</span></code> benchmarking tool see:
<a class="reference external" href="https://github.com/ga4gh/benchmarking-tools">https://github.com/ga4gh/benchmarking-tools</a> and
<a class="reference external" href="https://github.com/Illumina/hap.py">https://github.com/Illumina/hap.py</a></p>
</div>
</div>
</div>
<div class="section" id="additional-roc-stratifications">
<h4>Additional ROC stratifications<a class="headerlink" href="#additional-roc-stratifications" title="Permalink to this headline">¶</a></h4>
<p>All of the output modes produce the following ROC data files (unless
disabled by <code class="docutils literal notranslate"><span class="pre">--no-roc</span></code>):</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">weighted_roc.tsv</span></code> – contains ROC data derived from all analyzed
call variants, regardless of their representation. Columns include
the score field, and standard accuracy metrics such as true
positives, false positives, false negatives, precision, sensitivity,
and f-measure corresponding to each score threshold.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">snp_roc.tsv</span></code> – contains ROC data derived from only those variants
which were represented as SNPs. Since the representation conventions
can differ between the baseline and calls, there are some subtleties
to be aware of when interpreting metrics such as precision,
sensitivity, etc, described below.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">non_snp_roc.tsv</span></code> – contains ROC data derived from those
variants which were not represented as SNPs. As above, not all
metrics are computed for this file.</p></li>
</ul>
<p><code class="docutils literal notranslate"><span class="pre">vcfeval</span></code> also provides the ability to produce additional ROC data
files corresponding to preset and customized variant stratifications
with the following flags:</p>
<div class="section" id="preset-stratifications">
<h5>Preset stratifications<a class="headerlink" href="#preset-stratifications" title="Permalink to this headline">¶</a></h5>
<p>The <code class="docutils literal notranslate"><span class="pre">--roc-subset</span></code> flag allows selection from preset stratifications
based on variant type (according to their representation in the
relevant input VCF):</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">hom</span></code> – homozygous variants only</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">het</span></code> – heterozygous variants only</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">snp</span></code> – SNP variants (enabled by default)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">non-snp</span></code> – non-SNP variants (enabled by default)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">mnp</span></code> – multi-nucleotide polymorphisms only</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">indel</span></code> – length-changing variants only</p></li>
</ul>
<p>Multiple presets can be enabled in a single run, e.g. <code class="docutils literal notranslate"><span class="pre">--roc-subset</span> <span class="pre">hom,het,indel</span></code></p>
</div>
<div class="section" id="region-based-stratifications">
<h5>Region-based stratifications<a class="headerlink" href="#region-based-stratifications" title="Permalink to this headline">¶</a></h5>
<p>The <code class="docutils literal notranslate"><span class="pre">--roc-regions</span></code> flag produces a stratified ROC data file using only
variants that overlap regions specified in a user-supplied BED file. The
special syntax for this flag is: <code class="docutils literal notranslate"><span class="pre">--roc-regions</span> <span class="pre">LABEL=FILE</span></code>, where
<code class="docutils literal notranslate"><span class="pre">LABEL</span></code> is a short tag used to determine ROC output file names and
<code class="docutils literal notranslate"><span class="pre">FILE</span></code> is the path to the relevant BED file. For example, to produce
additional stratifications based on BED files partitioning the genome
based on GC content:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg vcfeval -t build37.sdf -b baseline.vcf.gz -c calls.vcf.gz \
  --roc-regions GC55TO60=/path/to/GCcontent/GRCh37_gc55to60_slop50.bed.gz \
  --roc-regions GC60TO65=/path/to/GCcontent/GRCh37_gc60to65_slop50.bed.gz
</pre></div>
</div>
</div>
<div class="section" id="custom-javascript-based-stratifications">
<h5>Custom JavaScript based stratifications<a class="headerlink" href="#custom-javascript-based-stratifications" title="Permalink to this headline">¶</a></h5>
<p>The above stratification flags will satisfy most common usages, but
<code class="docutils literal notranslate"><span class="pre">vcfeval</span></code> also includes the ability to write custom stratifications
using JavaScript expressions (similar to <code class="docutils literal notranslate"><span class="pre">vcffilter</span> <span class="pre">--keep-expr</span></code>). The
special syntax for this flag is: <code class="docutils literal notranslate"><span class="pre">--roc-expr</span> <span class="pre">LABEL=EXPRESSION</span></code>, where
<code class="docutils literal notranslate"><span class="pre">LABEL</span></code> is a short tag used to determine ROC output file names and
<code class="docutils literal notranslate"><span class="pre">EXPRESSION</span></code> is the JavaScript expression that accepts a variant for
inclusion in the stratification. This is most useful when the input VCFs
contain annotations useful for the stratification. For example, to
produce stratifications based on depth of coverage during variant
calling:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg vcfeval -t build37.sdf -b baseline.vcf.gz -c calls.vcf.gz \
  --roc-expr &quot;DP10TO20=has(INFO.DP) &amp;&amp; INFO.DP&gt;=10 &amp;&amp; INFO.DP&lt;20&quot; \
  --roc-expr &quot;DP20TO30=has(INFO.DP) &amp;&amp; INFO.DP&gt;=20 &amp;&amp; INFO.DP&lt;30&quot; \
  --roc-expr &quot;DP30TO40=has(INFO.DP) &amp;&amp; INFO.DP&gt;=30 &amp;&amp; INFO.DP&lt;40&quot;
</pre></div>
</div>
<p>Tips:</p>
<ul class="simple">
<li><p>Ensure the expression is valid to evaluate on all variants (for
example, take care when referring to sample fields names if the sample
names are different between baseline and calls files).</p></li>
<li><p>It may be useful to test or debug the expression (without the label)
via <code class="docutils literal notranslate"><span class="pre">vcffilter</span> <span class="pre">--keep-expr</span></code>.</p></li>
</ul>
<p>For more information on JavaScript expressions, see <a class="reference internal" href="appendix.html#rtg-javascript-filtering-api"><span class="std std-ref">RTG JavaScript filtering API</span></a></p>
</div>
</div>
<div class="section" id="benchmarking-comparisons-using-roc-and-precision-sensitivity-curves">
<h4>Benchmarking comparisons using ROC and precision/sensitivity curves<a class="headerlink" href="#benchmarking-comparisons-using-roc-and-precision-sensitivity-curves" title="Permalink to this headline">¶</a></h4>
<p>Multiple ROC data files (from a single or several <code class="docutils literal notranslate"><span class="pre">vcfeval</span></code> runs) can
be plotted with the <code class="docutils literal notranslate"><span class="pre">rocplot</span></code> command, which allows output to a PNG or
SVG image or analysis in an interactive GUI that provides zooming and
visualization of the effects of threshold adjustment. As these files are
simple tab-separated-value format, they can also be loaded into a
spreadsheet tool or processed with shell scripts.</p>
<p>While ROC curve analysis provides a much more thorough method for
examining the performance of a call set with respect to a baseline truth
set, for convenience, <code class="docutils literal notranslate"><span class="pre">vcfeval</span></code> also produces a <code class="docutils literal notranslate"><span class="pre">summary.txt</span></code> file
which indicates match summary statistics that correspond to two key
points on the ROC curve.  The first point is where all called variants
are included (i.e., no thresholding on a score value); and second point
corresponding to a score threshold that maximises the F-measure of the
curve. While this latter point is somewhat arbitrary, it represents a
balanced tradeoff between precision and sensitivity which is likely to
provide a fairer comparison when comparing call sets from different
callers.</p>
<p>Sometimes it is useful to perform the summary statistic evaluation at
some point other than maximized F-measure (for example when comparing
a large number of results at a particular precision level).  This can
be accomplished by specifying a different point using either the
<code class="docutils literal notranslate"><span class="pre">--at-precision</span></code> or <code class="docutils literal notranslate"><span class="pre">--at-sensitivity</span></code> flag with a value in the
range <code class="docutils literal notranslate"><span class="pre">[0,</span> <span class="pre">1]</span></code>.</p>
<p>Note that <code class="docutils literal notranslate"><span class="pre">vcfeval</span></code> reports true positives both counted using the
baseline variant representation as well as counted using the call
variant representation. When these numbers differ greatly, it indicates
a general difference in representational conventions used between the
two call sets. Since false negatives can only be measured in terms of
the baseline representation, sensitivity is defined as:</p>
<div class="math">
<p><img src="_images/math/b6f66d1803a9dcb5f12f25c57d4e43fb6584ca7e.png" alt="\text{Sensitivity} = \text{TP}_\text{baseline} / (\text{TP}_\text{baseline} + \text{FN})."/></p>
</div><p>Conversely since false positives can only be measured in terms of the
call representation, precision is defined as:</p>
<div class="math">
<p><img src="_images/math/67e012a427a90dc0c0f8a2d5939a95e5f6ffe591.png" alt="\text{Precision} = \text{TP}_\text{call} / (\text{TP}_\text{call} + \text{FP})."/></p>
</div><div class="admonition note">
<p class="admonition-title">Note</p>
<p>For definitions of the terminology used when evaluating caller
accuracy, see:
<a class="reference external" href="https://en.wikipedia.org/wiki/Receiver_operating_characteristic">https://en.wikipedia.org/wiki/Receiver_operating_characteristic</a>
and <a class="reference external" href="https://en.wikipedia.org/wiki/Sensitivity_and_specificity">https://en.wikipedia.org/wiki/Sensitivity_and_specificity</a></p>
</div>
</div>
<div class="section" id="benchmarking-performance-for-snps-versus-indels">
<h4>Benchmarking performance for SNPs versus indels<a class="headerlink" href="#benchmarking-performance-for-snps-versus-indels" title="Permalink to this headline">¶</a></h4>
<p>A common desire is to perform analysis separately for SNPs versus
indels. However, it is important to note that due the representation
ambiguity problem, it is not always trivial to decide in a global sense
whether a variant is a SNP or an indel or other complex variant. A group
of variants that may be represented as single SNPs in one call-set may
be represented as a single complex variant in another call-set. Consider
the following example reference and alternate haplotypes:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>     12345678901234567
REF: ATCGTAAATAAAATGCA
ALT: ATCGTAAAATAAATGCA
</pre></div>
</div>
<p>One variant caller might represent the haplotypes as the following VCF records:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>chr1 5 . T TA . . . GT 1/1
chr1 9 . TA T . . . GT 1/1
</pre></div>
</div>
<p>While another variant caller could represent the same haplotypes as:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>chr1 9 . T A . . . GT 1/1
chr1 10 . A T . . . GT 1/1
</pre></div>
</div>
<p>The decision as to which representation to use is essentially arbitrary,
yet one caller has used indels (and no SNPs), and the other has used
SNPs (and no indels). For this reason it is certainly a poor idea to
attempt to divide baseline and called variants into separate SNP and
indel datasets up front and perform evaluation on each set separately,
as any variants that use different representation categories will not be
matched across the independent comparisons. Any variant-type specific
metrics should be computed after matching is carried out on the full
variant sets.</p>
<p>Note that when there are different representational conventions between
the baseline and calls (or between calls from one variant caller and
another), then at some level there is really a semantic difference
between a “baseline indel” and a “call-set indel” (or “variant-caller-A
indel” and “variant-caller-B indel”), so caution should be applied when
making conclusions related to SNP versus indel accuracy.</p>
<p>In the <code class="docutils literal notranslate"><span class="pre">snp_roc.tsv</span></code> and <code class="docutils literal notranslate"><span class="pre">non_snp_roc.tsv</span></code> output files (and other
preset stratifications available via <code class="docutils literal notranslate"><span class="pre">--roc-subset</span></code>), <code class="docutils literal notranslate"><span class="pre">vcfeval</span></code>
notes the number of baseline and call variants of each variant
type. When considering benchmarking metrics in the absence of any
thresholding with respect to a score field, it is straight-forward to
use the previous formulae (i.e. sensitivity is computed using the counts
from baseline variants, and precision is computed using the counts from
called variants). When computing threshold-specific metrics for ROC data
points, the computation is more involved. Since only the call variants
contain the score field used to rank variants, the number of (say) TP
baseline indels that exceed threshold <img class="math" src="_images/math/888f7c323ac0341871e867220ae2d76467d74d6e.png" alt="x"/> is not
defined. <code class="docutils literal notranslate"><span class="pre">vcfeval</span></code> computes a scaled count as:</p>
<div class="math">
<p><img src="_images/math/b81c7a12342c0ee157b2c3f1bcfc4f91642187dc.png" alt="\text{TP}_\text{baseline\_indel}(x) = \text{TP}_\text{call\_indel}(x) \times \text{TP}_\text{baseline\_indel} / \text{TP}_\text{call\_indel}"/></p>
</div><p>and thus threshold-specific sensitivity is computed as</p>
<div class="math">
<p><img src="_images/math/f13fefe97363643ae6879e8f163616d0cf50ab3f.png" alt="\text{Sensitivity}_\text{indel}(x) = \text{TP}_\text{baseline\_indel}(x) / (\text{TP}_\text{baseline\_indel} + \text{FN}_\text{indel})"/></p>
</div><p>This scaling ensures that the end point of the variant type specific ROC
or precision/sensitivity curve ends at the same point that is obtained
when computing metrics without any threshold.</p>
<p>The scaling described above is applied to all of the preset
stratifications available via <code class="docutils literal notranslate"><span class="pre">--roc-subset</span></code>, but is not applied to
any custom stratifications produced via <code class="docutils literal notranslate"><span class="pre">--roc-regions</span></code> or
<code class="docutils literal notranslate"><span class="pre">--roc-expr</span></code>.</p>
</div>
<div class="section" id="variant-decomposition-and-benchmarking">
<h4>Variant decomposition and benchmarking<a class="headerlink" href="#variant-decomposition-and-benchmarking" title="Permalink to this headline">¶</a></h4>
<p>In general, it is not necessary to run any variant decomposition and/or
normalization on variant call sets prior to evaluation with <code class="docutils literal notranslate"><span class="pre">vcfeval</span></code>,
as the haplotype aware matching process can account for representation
differences. However, since matching is at the granularity of entire
variants, a single long complex call will be categorized as either
correct or incorrect, even if part of the call may match. If partial
credit in the case of long calls is of interest, <code class="docutils literal notranslate"><span class="pre">vcfeval</span></code> includes an
option to internally decompose variants prior to matching, using the
<code class="docutils literal notranslate"><span class="pre">--decompose</span></code> flag. This decomposition is applied to both baseline and
call variants, and any output VCFs will contain the decomposed
representation. External VCF decomposition (with more control over
decomposition options) is also available via <code class="docutils literal notranslate"><span class="pre">rtg</span> <span class="pre">vcfdecompose</span></code>.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#snp"><span class="std std-ref">snp</span></a>,
<a class="reference internal" href="#popsim"><span class="std std-ref">popsim</span></a>,
<a class="reference internal" href="#samplesim"><span class="std std-ref">samplesim</span></a>,
<a class="reference internal" href="#childsim"><span class="std std-ref">childsim</span></a>,
<a class="reference internal" href="#rocplot"><span class="std std-ref">rocplot</span></a>,
<a class="reference internal" href="#vcf2rocplot"><span class="std std-ref">vcf2rocplot</span></a>,
<a class="reference internal" href="#vcfdecompose"><span class="std std-ref">vcfdecompose</span></a></p>
</div>
</div>
</div>
<div class="section" id="vcffilter">
<h3>vcffilter<a class="headerlink" href="#vcffilter" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>Filters VCF records based on various criteria. When filtering on multiple samples, if any of the specified samples fail the criteria, the record will be
filtered. By default filtered records are removed, but see the –fail, –clear-failed-samples, and –fail-samples options for alternatives.</p>
<p><strong>Syntax:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg vcffilter [OPTION]... -i FILE -o FILE
</pre></div>
</div>
<p><strong>Examples:</strong></p>
<p>Keep only records where the sample has depth of coverage at least 5:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg vcffilter -i snps.vcf.gz -o snps_cov5.vcf.gz -d 5
</pre></div>
</div>
<p>Keep only biallelic records:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg vcffilter -i snps.vcf.gz -o snps_biallelic.vcf.gz --max-alleles 2
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<table class="docutils align-default">
<colgroup>
<col style="width: 4%" />
<col style="width: 17%" />
<col style="width: 79%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>File Input/Output</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--all-samples</span></code></p></td>
<td><p>Apply sample-specific criteria to all samples contained in the input VCF.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--bed-regions=FILE</span></code></p></td>
<td><p>If set, only read VCF records that overlap the ranges contained in the specified BED file.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-i</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--input=FILE</span></code></p></td>
<td><p>VCF file containing variants to be filtered. Use ‘-‘ to read from standard input.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-o</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--output=FILE</span></code></p></td>
<td><p>Output VCF file. Use ‘-‘ to write to standard output. This option is required, unless <code class="docutils literal notranslate"><span class="pre">--javascript</span></code> is being used.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--region=REGION</span></code></p></td>
<td><p>If set, only read VCF records within the specified range. The format is one of &lt;sequence_name&gt;, &lt;sequence_name&gt;:&lt;start&gt;-&lt;end&gt;, &lt;sequence_name&gt;:&lt;pos&gt;+&lt;length&gt; or
&lt;sequence_name&gt;:&lt;pos&gt;~&lt;padding&gt;</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--sample=STRING</span></code></p></td>
<td><p>Apply sample-specific criteria to the named sample contained in the input VCF. May be specified 0 or more times.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 4%" />
<col style="width: 18%" />
<col style="width: 78%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Filtering (Record based)</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-w</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--density-window=INT</span></code></p></td>
<td><p>Window within which multiple variants are discarded.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--exclude-bed=FILE</span></code></p></td>
<td><p>Discard all variants within the regions in this BED file.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--exclude-vcf=FILE</span></code></p></td>
<td><p>Discard all variants that overlap with the ones in this file.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--include-bed=FILE</span></code></p></td>
<td><p>Only keep variants within the regions in this BED file.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--include-vcf=FILE</span></code></p></td>
<td><p>Only keep variants that overlap with the ones in this file.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-j</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--javascript=STRING</span></code></p></td>
<td><p>Javascript filtering functions for determining whether to keep record. May be either an expression or a file name. May be specified 0 or more times.
<a class="reference internal" href="#javascript-examples"><span class="std std-ref">See Examples</span></a></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-e</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--keep-expr=STRING</span></code></p></td>
<td><p>Records for which this expression evaluates to true will be retained.
<a class="reference internal" href="#javascript-examples"><span class="std std-ref">See Examples</span></a></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-k</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--keep-filter=STRING</span></code></p></td>
<td><p>Only keep variants with this FILTER tag. May be specified 0 or more times, or as a comma separated list.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-K</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--keep-info=STRING</span></code></p></td>
<td><p>Only keep variants with this INFO tag. May be specified 0 or more times, or as a comma separated list.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--max-alleles=INT</span></code></p></td>
<td><p>Maximum number of alleles (REF included)</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-C</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--max-combined-read-depth=INT</span></code></p></td>
<td><p>Maximum allowed combined read depth.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-Q</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--max-quality=FLOAT</span></code></p></td>
<td><p>Maximum allowed quality.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--min-alleles=INT</span></code></p></td>
<td><p>Minimum number of alleles (REF included)</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-c</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--min-combined-read-depth=INT</span></code></p></td>
<td><p>Minimum allowed combined read depth.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-q</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--min-quality=FLOAT</span></code></p></td>
<td><p>Minimum allowed quality.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-r</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--remove-filter=STRING</span></code></p></td>
<td><p>Remove variants with this FILTER tag. May be specified 0 or more times, or as a comma separated list.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-R</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--remove-info=STRING</span></code></p></td>
<td><p>Remove variants with this INFO tag. May be specified 0 or more times, or as a comma separated list.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--remove-overlapping</span></code></p></td>
<td><p>Remove records that overlap with previous records.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 6%" />
<col style="width: 28%" />
<col style="width: 66%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Filtering (Sample based)</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-A</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--max-ambiguity-ratio=FLOAT</span></code></p></td>
<td><p>Maximum allowed ambiguity ratio.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--max-avr-score=FLOAT</span></code></p></td>
<td><p>Maximum allowed AVR score.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--max-denovo-score=FLOAT</span></code></p></td>
<td><p>Maximum de novo score threshold.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-G</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--max-genotype-quality=FLOAT</span></code></p></td>
<td><p>Maximum allowed genotype quality.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-D</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--max-read-depth=INT</span></code></p></td>
<td><p>Maximum allowed sample read depth.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--min-avr-score=FLOAT</span></code></p></td>
<td><p>Minimum allowed AVR score.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--min-denovo-score=FLOAT</span></code></p></td>
<td><p>Minimum de novo score threshold.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-g</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--min-genotype-quality=FLOAT</span></code></p></td>
<td><p>Minimum allowed genotype quality.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-d</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--min-read-depth=INT</span></code></p></td>
<td><p>Minimum allowed sample read depth.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--non-snps-only</span></code></p></td>
<td><p>Only keep where sample variant is MNP or INDEL.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--remove-all-same-as-ref</span></code></p></td>
<td><p>Remove where all samples are same as reference.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--remove-hom</span></code></p></td>
<td><p>Remove where sample is homozygous.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--remove-same-as-ref</span></code></p></td>
<td><p>Remove where sample is same as reference.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--snps-only</span></code></p></td>
<td><p>Only keep where sample variant is a simple SNP.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 6%" />
<col style="width: 28%" />
<col style="width: 66%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Reporting</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--clear-failed-samples</span></code></p></td>
<td><p>Retain failed records, set the sample GT field to missing.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-f</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--fail=STRING</span></code></p></td>
<td><p>Retain failed records, add the provided label to the FILTER field.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-F</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--fail-samples=STRING</span></code></p></td>
<td><p>Retain failed records, add the provided label to the sample FT field.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 6%" />
<col style="width: 24%" />
<col style="width: 70%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Utility</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-a</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--add-header=STRING|FILE</span></code></p></td>
<td><p>File containing VCF header lines to add, or a literal header line. May be specified 0 or more times.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-h</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--help</span></code></p></td>
<td><p>Print help on command-line flag usage.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-Z</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-gzip</span></code></p></td>
<td><p>Do not gzip the output.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-header</span></code></p></td>
<td><p>Prevent VCF header from being written.</p></td>
</tr>
</tbody>
</table>
<p><strong>Usage:</strong></p>
<p>Use <code class="docutils literal notranslate"><span class="pre">vcffilter</span></code> to get a subset of the results from variant calling
based on the filtering criteria supplied by the filter flags. Multiple
criteria can be specified at once, and advanced processing can be
specified via JavaScript scripting.</p>
<p>When filtering on multiple samples, if any of the specified samples fail
the criteria, the record will be filtered. The default behavior is for
filtered records to be excluded from output altogether, but
alternatively the records can be retained but with an additional
user-specified VCF <code class="docutils literal notranslate"><span class="pre">FILTER</span></code> status set via <code class="docutils literal notranslate"><span class="pre">--fail</span></code> option, or if
sample-specific filtering criteria is being applied, only those samples
can be filtered either by setting their <code class="docutils literal notranslate"><span class="pre">GT</span></code> field to missing by using
the <code class="docutils literal notranslate"><span class="pre">--clear-failed-samples</span></code> option, or by setting the <code class="docutils literal notranslate"><span class="pre">FORMAT</span></code>
<code class="docutils literal notranslate"><span class="pre">FT</span></code> field with a user-specified status via the <code class="docutils literal notranslate"><span class="pre">--fail-samples</span></code>
option.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">--bed-regions</span></code> option makes use of tabix indexes to avoid loading
VCF records outside the supplied regions, which can give faster
filtering performance. If the input VCF is not indexed or being read
from standard input, or if records failing filters are to be annotated
via the <code class="docutils literal notranslate"><span class="pre">--fail</span></code> option, use the <code class="docutils literal notranslate"><span class="pre">--include-bed</span></code> option instead.</p>
<p>The flags <code class="docutils literal notranslate"><span class="pre">--min-denovo-score</span></code> and <code class="docutils literal notranslate"><span class="pre">--max-denovo-score</span></code> can only be used
on a single sample. Records will only be kept if the specified sample is
flagged as a <em>de novo</em> variant and the score is within the range
specified by the flags. It will also only be kept if none of the other
samples for the record are also flagged as a <em>de novo</em> variant within
the specified score range.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">--add-header</span></code> option allows inserting arbitrary VCF header lines
into the output VCF. For more information, see <a class="reference internal" href="#vcfannotate"><span class="std std-ref">vcfannotate</span></a>.</p>
<p>A powerful general-purpose filtering capability has been included that
permits the specification of filter criteria as simple JavaScript
expressions (<code class="docutils literal notranslate"><span class="pre">--keep-expr</span></code>) or more comprehensive JavaScript processing
functions (<code class="docutils literal notranslate"><span class="pre">--javascript</span></code>). Both <code class="docutils literal notranslate"><span class="pre">--keep-expr</span></code> and <code class="docutils literal notranslate"><span class="pre">--javascript</span></code> can
take JavaScript on the command line or if a filename is supplied then
the script/expression will be read from that file. <code class="docutils literal notranslate"><span class="pre">--keep-expr</span></code> will be
applied before <code class="docutils literal notranslate"><span class="pre">--javascript</span></code>, so the <code class="docutils literal notranslate"><span class="pre">--javascript</span></code> record
function will not be called for records filtered out by <code class="docutils literal notranslate"><span class="pre">--keep-expr</span></code>.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p>For full details of functions available in <code class="docutils literal notranslate"><span class="pre">--keep-expr</span></code> and <code class="docutils literal notranslate"><span class="pre">--javascript</span></code> see <a class="reference internal" href="appendix.html#rtg-javascript-filtering-api"><span class="std std-ref">RTG JavaScript filtering API</span></a></p>
</div>
<div class="section" id="simple-filtering-by-javascript-expression-with-keep-expr">
<h4>Simple filtering by JavaScript expression with <code class="docutils literal notranslate"><span class="pre">--keep-expr</span></code><a class="headerlink" href="#simple-filtering-by-javascript-expression-with-keep-expr" title="Permalink to this headline">¶</a></h4>
<p>The <code class="docutils literal notranslate"><span class="pre">--keep-expr</span></code> flag aims to provide a convenient way to apply some
simple (typically one line) filtering expressions which are evaluated in
the context of each record. The final expression of the fragment must
evaluate to a boolean value. Records which evaluate to <code class="docutils literal notranslate"><span class="pre">true</span></code> will be
retained, while <code class="docutils literal notranslate"><span class="pre">false</span></code> will be removed. The value must be of type
boolean, simply being truthy/falsy (in the JavaScript sense) will raise
an error.</p>
<div class="section" id="keep-expr-examples">
<span id="expression-examples"></span><h5><code class="docutils literal notranslate"><span class="pre">--keep-expr</span></code> examples:<a class="headerlink" href="#keep-expr-examples" title="Permalink to this headline">¶</a></h5>
<p>The following expression keeps records where the <code class="docutils literal notranslate"><span class="pre">NA12878</span></code> sample has
<code class="docutils literal notranslate"><span class="pre">GQ</span></code> &gt; 30 and the total depth is &gt; 20. JavaScript will auto convert
numerical strings when comparing a string with a number, so calls to <code class="docutils literal notranslate"><span class="pre">parseInt</span></code> can be omitted.</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg vcffilter -i in.vcf.gz -o out.vcf.gz \
--keep-expr &quot;&#39;NA12878&#39;.GQ &gt; 30 &amp;&amp; INFO.DP &gt; 20&quot;
</pre></div>
</div>
<p>If the field of interest may contain the missing value (‘.’) or may be
entirely missing on a per-record basis, the <code class="docutils literal notranslate"><span class="pre">has()</span></code> function can be
used to control whether such records are kept vs filtered. For example,
to keep records with depth greater than 20, and remove any without a
<code class="docutils literal notranslate"><span class="pre">DP</span></code> annotation:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg vcffilter -i in.vcf.gz -o out.vcf.gz \
--keep-expr &quot;has(INFO.DP) &amp;&amp; INFO.DP &gt; 20&quot;
</pre></div>
</div>
<p>Alternatively, to keep records with depth greater than 20, as well as those without
a DP annotation:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg vcffilter -i in.vcf.gz -o out.vcf.gz \
--keep-expr &quot;!has(INFO.DP) || INFO.DP &gt; 20&quot;
</pre></div>
</div>
<p>The next example keeps records where all samples have a depth &gt; 10. The
standard JavaScript array methods <code class="docutils literal notranslate"><span class="pre">every</span></code> and <code class="docutils literal notranslate"><span class="pre">some</span></code> can be used to
apply a condition on every sample column.</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg vcffilter -i in.vcf.gz -o out.vcf.gz \
  --keep-expr &quot;SAMPLES.every(function(s) {return s.DP &gt; 10})&quot;
</pre></div>
</div>
<p>Similarly, the following example retains records where the <code class="docutils literal notranslate"><span class="pre">FILTER</span></code>
field is unset, or if set must be either <code class="docutils literal notranslate"><span class="pre">PASS</span></code> or <code class="docutils literal notranslate"><span class="pre">MED_QUAL</span></code>:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg vcffilter -i in.vcf.gz -o out.vcf.gz \
  --keep-expr &quot;FILTER.every(function(f) {return f == &#39;PASS&#39; || f == &#39;MED_QUAL&#39;})&quot;
</pre></div>
</div>
<p>Note that multi-valued <code class="docutils literal notranslate"><span class="pre">INFO</span></code> and <code class="docutils literal notranslate"><span class="pre">FORMAT</span></code> fields are not split into
sub-values, so in some cases correct filtering may require splitting the
values first. For example, to select bi-allelic records with <code class="docutils literal notranslate"><span class="pre">AF</span></code>
greater than 0.1, the following simple selection will work:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg vcffilter -i in.vcf.gz -o out.vcf.gz \
  --keep-expr &quot;INFO.AF&gt;=0.1&quot;
</pre></div>
</div>
<p>However, in the presence of multi-allelic records, something like the
following is required:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg vcffilter -i in.vcf.gz -o out.vcf.gz \
  --keep-expr &quot;INFO.AF.split(&#39;,&#39;).some(function(af) {return af &gt;= 0.1})&quot;
</pre></div>
</div>
</div>
</div>
<div class="section" id="advanced-javascript-filtering-with-javascript">
<h4>Advanced JavaScript filtering with <code class="docutils literal notranslate"><span class="pre">--javascript</span></code><a class="headerlink" href="#advanced-javascript-filtering-with-javascript" title="Permalink to this headline">¶</a></h4>
<p>The <code class="docutils literal notranslate"><span class="pre">--javascript</span></code> option aims to support more complicated processing
than <code class="docutils literal notranslate"><span class="pre">--keep-expr</span></code>, permitting modification of the output VCF, or
supporting use cases where the script is tasked to compute and output
alternative information in addition to (or instead of) the output VCF.
The scripts specified by the user are evaluated once at the start of
processing. Two special functions may be defined in a <code class="docutils literal notranslate"><span class="pre">--javascript</span></code>
script, which will then be executed in different contexts:</p>
<ul class="simple">
<li><p>A function with the name <code class="docutils literal notranslate"><span class="pre">record</span></code> will be executed once for each VCF
record. If the <code class="docutils literal notranslate"><span class="pre">record</span></code> function has a return value it must have type
boolean. Records which evaluate to <code class="docutils literal notranslate"><span class="pre">true</span></code> will be retained, while
<code class="docutils literal notranslate"><span class="pre">false</span></code> will be removed. If the record function has no return value
then the record will be retained. The <code class="docutils literal notranslate"><span class="pre">record</span></code> function is applied
after any <code class="docutils literal notranslate"><span class="pre">--keep-expr</span></code> expression.</p></li>
<li><p>A function with the name <code class="docutils literal notranslate"><span class="pre">end</span></code> will be called once at the end of
processing. This allows reporting of summary statistics collected
during the filter process.</p></li>
</ul>
<p>This <code class="docutils literal notranslate"><span class="pre">--javascript</span></code> flag may be specified multiple times, they will be
evaluated in order, in a shared JavaScript namespace, before VCF
processing commences. This permits a use case where an initial
JavaScript expression supplies parameter values which will be required
by a subsequent JavaScript file.</p>
<div class="section" id="example-javascript-scripts">
<span id="javascript-examples"></span><h5>Example <code class="docutils literal notranslate"><span class="pre">--javascript</span></code> scripts:<a class="headerlink" href="#example-javascript-scripts" title="Permalink to this headline">¶</a></h5>
<p>To find indels with length greater than 5, save the following to a file
named <code class="docutils literal notranslate"><span class="pre">find-indels.js</span></code>:</p>
<div class="highlight-javascript notranslate"><div class="highlight"><pre><span></span><span class="c1">// Finds indels with length &gt; 5</span>
<span class="kd">function</span> <span class="nx">record</span><span class="p">()</span> <span class="p">{</span>
  <span class="kd">var</span> <span class="nx">deltas</span> <span class="o">=</span> <span class="nx">ALT</span><span class="p">.</span><span class="nx">map</span><span class="p">(</span><span class="kd">function</span> <span class="p">(</span><span class="nx">alt</span><span class="p">)</span> <span class="p">{</span>
    <span class="k">return</span> <span class="nb">Math</span><span class="p">.</span><span class="nx">abs</span><span class="p">(</span><span class="nx">alt</span><span class="p">.</span><span class="nx">length</span> <span class="o">-</span> <span class="nx">REF</span><span class="p">.</span><span class="nx">length</span><span class="p">);</span>
  <span class="p">});</span>
  <span class="k">return</span> <span class="nx">deltas</span><span class="p">.</span><span class="nx">some</span><span class="p">(</span><span class="kd">function</span> <span class="p">(</span><span class="nx">delta</span><span class="p">)</span> <span class="p">{</span><span class="k">return</span> <span class="nx">delta</span> <span class="o">&gt;</span> <span class="mi">5</span><span class="p">});</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Then perform the filtering via:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg vcffilter -i in.vcf.gz -o out.vcf.gz --javascript find-indels.js
</pre></div>
</div>
<p>The following example derives a new <code class="docutils literal notranslate"><span class="pre">FORMAT</span></code> column containing variant
allelic fraction to two decimal places based on the values in the <code class="docutils literal notranslate"><span class="pre">AD</span></code>
and <code class="docutils literal notranslate"><span class="pre">DP</span></code> <code class="docutils literal notranslate"><span class="pre">FORMAT</span></code> annotations, for every sample contained in the
VCF. Save the following to a file named <code class="docutils literal notranslate"><span class="pre">add-vaf.js</span></code>:</p>
<div class="highlight-javascript notranslate"><div class="highlight"><pre><span></span><span class="c1">// Derive new VAF FORMAT field for each sample</span>
<span class="nx">ensureFormatHeader</span><span class="p">(</span><span class="s1">&#39;##FORMAT=&lt;ID=VAF,Number=1,Type=Float,&#39;</span> <span class="o">+</span>
  <span class="s1">&#39;Description=&quot;Variant Allelic Fraction&quot;&gt;&#39;</span><span class="p">);</span>

<span class="kd">function</span> <span class="nx">record</span><span class="p">()</span> <span class="p">{</span>
  <span class="nx">SAMPLES</span><span class="p">.</span><span class="nx">forEach</span><span class="p">(</span><span class="kd">function</span><span class="p">(</span><span class="nx">sample</span><span class="p">)</span> <span class="p">{</span>
    <span class="c1">// Take all but the first AD value as numerics</span>
    <span class="kd">var</span> <span class="nx">altDepths</span> <span class="o">=</span> <span class="nx">sample</span><span class="p">.</span><span class="nx">AD</span><span class="p">.</span><span class="nx">split</span><span class="p">(</span><span class="s2">&quot;,&quot;</span><span class="p">).</span><span class="nx">slice</span><span class="p">(</span><span class="mi">1</span><span class="p">);</span>
    <span class="c1">// Find the max</span>
    <span class="kd">var</span> <span class="nx">maxAltDepth</span> <span class="o">=</span> <span class="nb">Math</span><span class="p">.</span><span class="nx">max</span><span class="p">.</span><span class="nx">apply</span><span class="p">(</span><span class="kc">null</span><span class="p">,</span> <span class="nx">altDepths</span><span class="p">);</span>
    <span class="k">if</span> <span class="p">(</span><span class="nx">maxAltDepth</span> <span class="o">&gt;</span> <span class="mi">0</span><span class="p">)</span> <span class="p">{</span>
      <span class="nx">sample</span><span class="p">.</span><span class="nx">VAF</span> <span class="o">=</span> <span class="p">(</span><span class="nx">maxAltDepth</span> <span class="o">/</span> <span class="nx">sample</span><span class="p">.</span><span class="nx">DP</span><span class="p">).</span><span class="nx">toFixed</span><span class="p">(</span><span class="mi">2</span><span class="p">);</span>
    <span class="p">}</span>
  <span class="p">});</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Then run the filtering via:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg vcffilter -i in.vcf.gz -o out.vcf.gz --javascript add-vaf.js
</pre></div>
</div>
<p>The next example produces a table of binned indel lengths, save the
following to a file named <code class="docutils literal notranslate"><span class="pre">indel-lengths.js</span></code>:</p>
<div class="highlight-javascript notranslate"><div class="highlight"><pre><span></span><span class="c1">// bin breakpoints can be customised by defining your own bins[] in a</span>
<span class="c1">// previous -j flag</span>
<span class="k">if</span> <span class="p">(</span><span class="k">typeof</span> <span class="nx">bins</span> <span class="o">==</span> <span class="s2">&quot;undefined&quot;</span><span class="p">)</span> <span class="p">{</span>
  <span class="kd">var</span> <span class="nx">bins</span> <span class="o">=</span> <span class="p">[</span><span class="o">-</span><span class="mi">10</span><span class="p">,</span> <span class="o">-</span><span class="mi">5</span><span class="p">,</span> <span class="o">-</span><span class="mi">3</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">6</span><span class="p">,</span> <span class="mi">11</span><span class="p">];</span>
<span class="p">}</span>

<span class="kd">var</span> <span class="nx">counts</span> <span class="o">=</span> <span class="p">[</span><span class="mi">0</span><span class="p">];</span>
<span class="nx">bins</span><span class="p">.</span><span class="nx">forEach</span><span class="p">(</span><span class="kd">function</span> <span class="p">()</span> <span class="p">{</span><span class="nx">counts</span><span class="p">.</span><span class="nx">push</span><span class="p">(</span><span class="mi">0</span><span class="p">)});</span>
<span class="kd">function</span> <span class="nx">record</span><span class="p">()</span> <span class="p">{</span>
  <span class="k">if</span> <span class="p">(</span><span class="nx">ALT</span><span class="p">.</span><span class="nx">length</span> <span class="o">==</span> <span class="mi">0</span><span class="p">)</span> <span class="p">{</span>
    <span class="k">return</span> <span class="kc">false</span><span class="p">;</span>
  <span class="p">}</span>
  <span class="kd">var</span> <span class="nx">deltas</span> <span class="o">=</span> <span class="nx">ALT</span><span class="p">.</span><span class="nx">map</span><span class="p">(</span><span class="kd">function</span> <span class="p">(</span><span class="nx">alt</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="nx">alt</span><span class="p">.</span><span class="nx">length</span> <span class="o">-</span> <span class="nx">REF</span><span class="p">.</span><span class="nx">length</span><span class="p">;</span> <span class="p">});</span>
  <span class="kd">var</span> <span class="nx">maxDel</span> <span class="o">=</span> <span class="nb">Math</span><span class="p">.</span><span class="nx">min</span><span class="p">.</span><span class="nx">apply</span><span class="p">(</span><span class="kc">null</span><span class="p">,</span> <span class="nx">deltas</span><span class="p">);</span>
  <span class="kd">var</span> <span class="nx">maxIns</span> <span class="o">=</span> <span class="nb">Math</span><span class="p">.</span><span class="nx">max</span><span class="p">.</span><span class="nx">apply</span><span class="p">(</span><span class="kc">null</span><span class="p">,</span> <span class="nx">deltas</span><span class="p">);</span>
  <span class="kd">var</span> <span class="nx">delta</span> <span class="o">=</span> <span class="nb">Math</span><span class="p">.</span><span class="nx">abs</span><span class="p">(</span><span class="nx">maxDel</span><span class="p">)</span> <span class="o">&gt;</span> <span class="nx">maxIns</span> <span class="o">?</span> <span class="nx">maxDel</span> <span class="o">:</span> <span class="nx">maxIns</span><span class="p">;</span>

  <span class="k">if</span> <span class="p">(</span><span class="nx">delta</span> <span class="o">==</span> <span class="mi">0</span><span class="p">)</span> <span class="p">{</span>
    <span class="k">return</span> <span class="kc">false</span><span class="p">;</span>
  <span class="p">}</span>
  <span class="k">for</span> <span class="p">(</span><span class="kd">var</span> <span class="nx">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="nx">i</span> <span class="o">&lt;</span> <span class="nx">bins</span><span class="p">.</span><span class="nx">length</span><span class="p">;</span> <span class="nx">i</span><span class="o">++</span><span class="p">)</span> <span class="p">{</span>
    <span class="k">if</span> <span class="p">(</span><span class="nx">delta</span> <span class="o">&lt;</span> <span class="nx">bins</span><span class="p">[</span><span class="nx">i</span><span class="p">])</span> <span class="p">{</span>
      <span class="nx">counts</span><span class="p">[</span><span class="nx">i</span><span class="p">]</span><span class="o">++</span><span class="p">;</span>
      <span class="k">break</span><span class="p">;</span>
    <span class="p">}</span>
  <span class="p">}</span>
  <span class="k">if</span> <span class="p">(</span><span class="nx">delta</span> <span class="o">&gt;</span> <span class="nx">bins</span><span class="p">[</span><span class="nx">bins</span><span class="p">.</span><span class="nx">length</span> <span class="o">-</span> <span class="mi">1</span><span class="p">])</span> <span class="p">{</span>
    <span class="nx">counts</span><span class="p">[</span><span class="nx">counts</span><span class="p">.</span><span class="nx">length</span> <span class="o">-</span> <span class="mi">1</span><span class="p">]</span><span class="o">++</span><span class="p">;</span>
  <span class="p">}</span>
  <span class="k">return</span> <span class="kc">false</span><span class="p">;</span>
<span class="p">}</span>

<span class="kd">function</span> <span class="nx">end</span><span class="p">()</span> <span class="p">{</span>
  <span class="nx">print</span><span class="p">(</span><span class="s2">&quot;Delta\\tCount&quot;</span><span class="p">);</span>
  <span class="k">for</span> <span class="p">(</span><span class="kd">var</span> <span class="nx">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="nx">i</span> <span class="o">&lt;</span> <span class="nx">bins</span><span class="p">.</span><span class="nx">length</span><span class="p">;</span> <span class="nx">i</span><span class="o">++</span><span class="p">)</span> <span class="p">{</span>
    <span class="nx">print</span><span class="p">(</span><span class="s2">&quot;&lt;&quot;</span> <span class="o">+</span> <span class="nx">bins</span><span class="p">[</span><span class="nx">i</span><span class="p">]</span> <span class="o">+</span> <span class="s2">&quot;\\t&quot;</span> <span class="o">+</span> <span class="nx">counts</span><span class="p">[</span><span class="nx">i</span><span class="p">]);</span>
  <span class="p">}</span>
  <span class="nx">print</span><span class="p">(</span><span class="s2">&quot;&gt;&quot;</span> <span class="o">+</span> <span class="nx">bins</span><span class="p">[</span><span class="nx">bins</span><span class="p">.</span><span class="nx">length</span> <span class="o">-</span> <span class="mi">1</span><span class="p">]</span> <span class="o">+</span> <span class="s2">&quot;\\t&quot;</span> <span class="o">+</span> <span class="nx">counts</span><span class="p">[</span><span class="nx">counts</span><span class="p">.</span><span class="nx">length</span> <span class="o">-</span> <span class="mi">1</span><span class="p">]);</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Then run the filtering via:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg vcffilter -i in.vcf.gz -o out.vcf.gz --javascript indel-lengths.js
</pre></div>
</div>
<p>We could use this same script with adjusted bins and omitting the output
of the VCF via:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg vcffilter -i in.vcf.gz -j &quot;var bins = [-20, -10, 0, 20, 20];&quot; \
  -j indel-lengths.js
</pre></div>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p>For full details of functions available in <code class="docutils literal notranslate"><span class="pre">--keep-expr</span></code> and <code class="docutils literal notranslate"><span class="pre">--javascript</span></code> see <a class="reference internal" href="appendix.html#rtg-javascript-filtering-api"><span class="std std-ref">RTG JavaScript filtering API</span></a></p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#snp"><span class="std std-ref">snp</span></a>,
<a class="reference internal" href="#family"><span class="std std-ref">family</span></a>,
<a class="reference internal" href="#somatic"><span class="std std-ref">somatic</span></a>,
<a class="reference internal" href="#population"><span class="std std-ref">population</span></a>,
<a class="reference internal" href="#vcfannotate"><span class="std std-ref">vcfannotate</span></a>,
<a class="reference internal" href="#vcfmerge"><span class="std std-ref">vcfmerge</span></a>,
<a class="reference internal" href="#vcfsubset"><span class="std std-ref">vcfsubset</span></a></p>
</div>
</div>
</div>
</div>
<div class="section" id="vcfmerge">
<h3>vcfmerge<a class="headerlink" href="#vcfmerge" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>Combines the contents of two or more VCF files. The <code class="docutils literal notranslate"><span class="pre">vcfmerge</span></code> command
can concatenate the outputs of per-chromosome variant detection runs to
create a complete genome VCF file, and also merge VCF outputs from
multiple samples to form a multi-sample VCF file.</p>
<p><strong>Syntax:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg vcfmerge [OPTION]... -o FILE FILE+
</pre></div>
</div>
<p><strong>Example:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg vcfmerge -o merged.vcf.gz snp1.vcf.gz snp2.vcf.gz
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<table class="docutils align-default">
<colgroup>
<col style="width: 4%" />
<col style="width: 15%" />
<col style="width: 81%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>File Input/Output</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--bed-regions=FILE</span></code></p></td>
<td><p>If set, only read VCF records that overlap the ranges contained in the specified BED file.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-I</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--input-list-file=FILE</span></code></p></td>
<td><p>File containing a list of VCF format files (1 per line) to be merged.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-o</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--output=FILE</span></code></p></td>
<td><p>Output VCF file. Use ‘-‘ to write to standard output.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--region=REGION</span></code></p></td>
<td><p>If set, only read VCF records within the specified range. The format is one of &lt;sequence_name&gt;, &lt;sequence_name&gt;:&lt;start&gt;-&lt;end&gt;, &lt;sequence_name&gt;:&lt;pos&gt;+&lt;length&gt; or
&lt;sequence_name&gt;:&lt;pos&gt;~&lt;padding&gt;</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">FILE+</span></code></p></td>
<td><p>Input VCF files to merge. May be specified 0 or more times.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 4%" />
<col style="width: 17%" />
<col style="width: 79%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Utility</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-a</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--add-header=STRING|FILE</span></code></p></td>
<td><p>File containing VCF header lines to add, or a literal header line. May be specified 0 or more times.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-f</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--force-merge=STRING</span></code></p></td>
<td><p>Allow merging of specified header ID even when descriptions do not match. May be specified 0 or more times, or as a comma separated list.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-F</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--force-merge-all</span></code></p></td>
<td><p>Attempt merging of all non-matching header declarations.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-h</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--help</span></code></p></td>
<td><p>Print help on command-line flag usage.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-Z</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-gzip</span></code></p></td>
<td><p>Do not gzip the output.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-header</span></code></p></td>
<td><p>Prevent VCF header from being written.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-merge-alts</span></code></p></td>
<td><p>Do not merge multiple records if the ALTs are different.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-merge-records</span></code></p></td>
<td><p>Do not merge multiple records at the same position into one.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--preserve-formats</span></code></p></td>
<td><p>Do not merge multiple records containing unmergeable FORMAT fields (Default is to remove those FORMAT fields so the variants can be combined)</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--stats</span></code></p></td>
<td><p>Output statistics for the merged VCF file.</p></td>
</tr>
</tbody>
</table>
<p><strong>Usage:</strong></p>
<p>The <code class="docutils literal notranslate"><span class="pre">vcfmerge</span></code> command takes a list of VCF files and outputs to a
single VCF file. Each VCF file must be block compressed and have a
corresponding tabix index file, which is the default for outputs from
RTG variant detection tools, but may also be created from an existing
VCF file using the RTG <code class="docutils literal notranslate"><span class="pre">bgzip</span></code> and <code class="docutils literal notranslate"><span class="pre">index</span></code> commands.</p>
<p>There are two primary usage scenarios for the <code class="docutils literal notranslate"><span class="pre">vcfmerge</span></code> command. The
first is to combine input VCFs corresponding to different genomic
regions (for example, if variant calling was carried out for each
chromosome independently on different nodes of a compute cluster). The
second scenario is when combining VCFs containing variant calls for
different samples (e.g. combining calls made for separate cohorts into a
single VCF).</p>
<p>The input files must have consistent header lines, although specific
similar header lines can be forced to merge using the <code class="docutils literal notranslate"><span class="pre">--force-merge</span></code>
parameter, or inconsistent header checking can be entirely disabled with
<code class="docutils literal notranslate"><span class="pre">--force-merge-all</span></code>.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">--add-header</span></code> option allows inserting arbitrary VCF header lines
into the output VCF. For more information, see <a class="reference internal" href="#vcfannotate"><span class="std std-ref">vcfannotate</span></a>.</p>
<div class="section" id="merging-records-at-the-same-position">
<h4>Merging records at the same position<a class="headerlink" href="#merging-records-at-the-same-position" title="Permalink to this headline">¶</a></h4>
<p>When multiple records occur with the same position and length on the
reference, <code class="docutils literal notranslate"><span class="pre">vcfmerge</span></code> will attempt to combine the records into a
single record. Combining multiple fully annotated records is
non-trivial, and can lead to loss of information depending on the
annotations present. The default behavior takes a pragmatic approach to
merging, with options to adjust the merging behavior as
required. Multi-record merging can be disabled entirely by setting
<code class="docutils literal notranslate"><span class="pre">--no-merge-records</span></code>.</p>
<p>The first point to note is that the <code class="docutils literal notranslate"><span class="pre">QUAL</span></code>, <code class="docutils literal notranslate"><span class="pre">FILTER</span></code>, <code class="docutils literal notranslate"><span class="pre">INFO</span></code>
fields are taken from the first record only (those values from other
records at the position are ignored).</p>
<p>If the combined record would result in a change in the set of ALT
alleles, any VCF <code class="docutils literal notranslate"><span class="pre">INFO</span></code> or <code class="docutils literal notranslate"><span class="pre">FORMAT</span></code> fields declared to be of type
<code class="docutils literal notranslate"><span class="pre">A</span></code>, <code class="docutils literal notranslate"><span class="pre">G</span></code>, or <code class="docutils literal notranslate"><span class="pre">R</span></code> cannot meaningfully be retained.  By default such
fields will be removed or set to the missing value (<code class="docutils literal notranslate"><span class="pre">.</span></code>).  (Other
annotations may also become semantically meaningless, but it isn’t
possible to tell in general.)</p>
<p>Similarly, if multiple input records with the same position and length
on the reference contain information for the same sample, only the
information from the first record will be retained.</p>
<p>These behaviors can be altered with additional flags:
<code class="docutils literal notranslate"><span class="pre">--no-merge-alts</span></code> will simply prevent record merging if the ALTs are
not the same across the records; <code class="docutils literal notranslate"><span class="pre">--preserve-formats</span></code> will attempt
merging as long as the records do not contain problematic <code class="docutils literal notranslate"><span class="pre">A</span></code>, <code class="docutils literal notranslate"><span class="pre">G</span></code>,
or <code class="docutils literal notranslate"><span class="pre">R</span></code> annotations, or contain the same sample.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#snp"><span class="std std-ref">snp</span></a>,
<a class="reference internal" href="#family"><span class="std std-ref">family</span></a>,
<a class="reference internal" href="#population"><span class="std std-ref">population</span></a>,
<a class="reference internal" href="#somatic"><span class="std std-ref">somatic</span></a>,
<a class="reference internal" href="#vcffilter"><span class="std std-ref">vcffilter</span></a>,
<a class="reference internal" href="#vcfannotate"><span class="std std-ref">vcfannotate</span></a>,
<a class="reference internal" href="#vcfsubset"><span class="std std-ref">vcfsubset</span></a>,
<a class="reference internal" href="#bgzip"><span class="std std-ref">bgzip</span></a>,
<a class="reference internal" href="#index"><span class="std std-ref">index</span></a></p>
</div>
</div>
</div>
<div class="section" id="vcfsplit">
<h3>vcfsplit<a class="headerlink" href="#vcfsplit" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>Splits samples contained within a VCF into separate files, one per
sample.</p>
<p><strong>Syntax:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg vcfsplit [OPTION]... -i FILE -o DIR
</pre></div>
</div>
<p><strong>Example:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg vcfsplit --keep-sample NA12878,NA12891,NA12892 -i population-ceph-calls.vcf.gz -o trio-vcfs
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<table class="docutils align-default">
<colgroup>
<col style="width: 4%" />
<col style="width: 16%" />
<col style="width: 80%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>File Input/Output</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--bed-regions=FILE</span></code></p></td>
<td><p>If set, only read VCF records that overlap the ranges contained in the specified BED file.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-i</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--input=FILE</span></code></p></td>
<td><p>The input VCF, or ‘-‘ to read from standard input.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-o</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--output=DIR</span></code></p></td>
<td><p>Directory for output.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--region=REGION</span></code></p></td>
<td><p>If set, only read VCF records within the specified range. The format is one of &lt;sequence_name&gt;, &lt;sequence_name&gt;:&lt;start&gt;-&lt;end&gt;, &lt;sequence_name&gt;:&lt;pos&gt;+&lt;length&gt; or
&lt;sequence_name&gt;:&lt;pos&gt;~&lt;padding&gt;</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 5%" />
<col style="width: 19%" />
<col style="width: 76%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Filtering</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--keep-ref</span></code></p></td>
<td><p>Keep records where the sample is reference.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--keep-sample=STRING|FILE</span></code></p></td>
<td><p>File containing sample IDs to select, or a literal sample name. May be specified 0 or more times, or as a comma separated list.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--remove-sample=STRING|FILE</span></code></p></td>
<td><p>File containing sample IDs to ignore, or a literal sample name. May be specified 0 or more times, or as a comma separated list.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 7%" />
<col style="width: 27%" />
<col style="width: 67%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Utility</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-h</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--help</span></code></p></td>
<td><p>Print help on command-line flag usage.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-Z</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-gzip</span></code></p></td>
<td><p>Do not gzip the output.</p></td>
</tr>
</tbody>
</table>
<p><strong>Usage:</strong></p>
<p>The <code class="docutils literal notranslate"><span class="pre">vcfsplit</span></code> command allows producing separate single-sample VCF
files from a single multi-sample VCF, and is more efficient than running
<code class="docutils literal notranslate"><span class="pre">vcfsubset</span></code> separately for each required sample, particularly when the
input VCF contains many samples, as the input VCF only needs to be read
once.</p>
<p>The output VCFs are all written into the specified output directory, as
<code class="docutils literal notranslate"><span class="pre">sample_name.vcf.gz</span></code>. For any particular output VCF, only records
where the sample has a non-reference genotype will be output, unless
<code class="docutils literal notranslate"><span class="pre">--keep-ref</span></code> is used.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#vcfsubset"><span class="std std-ref">vcfsubset</span></a></p>
</div>
</div>
<div class="section" id="vcfstats">
<h3>vcfstats<a class="headerlink" href="#vcfstats" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>Display simple statistics about the contents of a set of VCF files.</p>
<p><strong>Syntax:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg vcfstats [OPTION]... FILE+
</pre></div>
</div>
<p><strong>Example:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg vcfstats /data/human/wgs/NA19240/snp_chr5.vcf.gz

Location                      : /data/human/wgs/NA19240/snp_chr5.vcf.gz
Passed Filters                : 283144
Failed Filters                : 83568
SNPs                          : 241595
MNPs                          : 5654
Insertions                    : 15424
Deletions                     : 14667
Indels                        : 1477
Unchanged                     : 4327
SNP Transitions/Transversions : 1.93 (210572/108835)
Total Het/Hom ratio           : 2.13 (189645/89172)
SNP Het/Hom ratio             : 2.12 (164111/77484)
MNP Het/Hom ratio             : 3.72 (4457/1197)
Insertion Het/Hom ratio       : 1.69 (9695/5729)
Deletion Het/Hom ratio        : 2.33 (10263/4404)
Indel Het/Hom ratio           : 3.13 (1119/358)
Insertion/Deletion ratio      : 1.05 (15424/14667)
Indel/SNP+MNP ratio           : 0.13 (31568/247249)
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<table class="docutils align-default">
<colgroup>
<col style="width: 3%" />
<col style="width: 13%" />
<col style="width: 84%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>File Input/Output</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--known</span></code></p></td>
<td><p>Set to only calculate statistics for known variants.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--novel</span></code></p></td>
<td><p>Set to only calculate statistics for novel variants.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--sample=FILE</span></code></p></td>
<td><p>Set to only calculate statistics for the specified sample. (Default is to include all samples). May be specified 0 or more times.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p>FILE+</p></td>
<td><p>VCF file from which to derive statistics. Use ‘-‘ to read from standard input. Must be specified 1 or more times.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 6%" />
<col style="width: 34%" />
<col style="width: 61%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Reporting</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--allele-lengths</span></code></p></td>
<td><p>Set to output variant length histogram.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 15%" />
<col style="width: 21%" />
<col style="width: 64%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Utility</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-h</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--help</span></code></p></td>
<td><p>Prints help on command-line flag usage.</p></td>
</tr>
</tbody>
</table>
<p><strong>Usage:</strong></p>
<p>Use the <code class="docutils literal notranslate"><span class="pre">vcfstats</span></code> command to display summary statistics for a set of
VCF files. If a VCF file contains multiple sample columns, the
statistics for each sample are shown individually.</p>
<p>When determining the categorization of a REF to ALT transformation, some
normalization is carried out to ignore same as reference bases at the
start and end of the alleles. Thus the following REF to ALT
transformations are categorized as <code class="docutils literal notranslate"><span class="pre">SNPs</span></code>:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>A    -&gt; G      (simple case)
ATGC -&gt; ATGG   (leading bases match)
ATGC -&gt; ACGC   (leading and trailing bases match)
</pre></div>
</div>
<p>Cases where multiple bases change, but the lengths of the two alleles do
not are considered to be <code class="docutils literal notranslate"><span class="pre">MNPs</span></code>:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>ATGC -&gt; TTGG   (two bases change)
ATGC -&gt; GTCT   (three bases change)
</pre></div>
</div>
<p>Cases where there is pure addition or removal of bases are classified as
<code class="docutils literal notranslate"><span class="pre">Insertions</span></code> or <code class="docutils literal notranslate"><span class="pre">Deletions</span></code> respectively:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>A     -&gt; AT      (one base insertion)
ATT   -&gt; ATTTT   (two base insertion)
AT    -&gt; A       (one base deletion)
ATTTT -&gt; ATT     (two base deletion)
</pre></div>
</div>
<p>The remaining case is there there is a length change between the REF and
ALT, but it is not pure. These are called <code class="docutils literal notranslate"><span class="pre">Indels</span></code>:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>ATT   -&gt; CTTT    (one base changed, one base inserted)
CTTT  -&gt; ATT     (one base changed, one base deleted)
</pre></div>
</div>
<p>In the per-sample summary output of <code class="docutils literal notranslate"><span class="pre">vcfstats</span></code>, each genotype is
classified as a whole into one of the above categories, preferring the
more complex of the transformations when ploidy is greater than one.</p>
<p>When computing the per-sample variant length histograms, note that the
histograms are incremented for each called allele (thus a diploid
homozygous call will increment the appropriate cell by two), and the
length of an indel is taken as the change in length rather than the
overall length.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#snp"><span class="std std-ref">snp</span></a>,
<a class="reference internal" href="#family"><span class="std std-ref">family</span></a>,
<a class="reference internal" href="#somatic"><span class="std std-ref">somatic</span></a>,
<a class="reference internal" href="#vcffilter"><span class="std std-ref">vcffilter</span></a>,
<a class="reference internal" href="#vcfmerge"><span class="std std-ref">vcfmerge</span></a>,
<a class="reference internal" href="#vcfsubset"><span class="std std-ref">vcfsubset</span></a></p>
</div>
</div>
<div class="section" id="vcfsubset">
<h3>vcfsubset<a class="headerlink" href="#vcfsubset" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>Create a VCF file containing a subset of the original columns.</p>
<p><strong>Syntax:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg vcfsubset [OPTION]... -i FILE -o FILE
</pre></div>
</div>
<p><strong>Example:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg vcfsubset -i snps.vcf.gz -o frequency.vcf.gz --keep-info AF --remove-samples
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<table class="docutils align-default">
<colgroup>
<col style="width: 4%" />
<col style="width: 16%" />
<col style="width: 80%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>File Input/Output</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--bed-regions=FILE</span></code></p></td>
<td><p>If set, only read VCF records that overlap the ranges contained in the specified BED file.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-i</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--input=FILE</span></code></p></td>
<td><p>VCF file containing variants to manipulate. Use ‘-‘ to read from standard input.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-o</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--output=FILE</span></code></p></td>
<td><p>Output VCF file. Use ‘-‘ to write to standard output.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--region=REGION</span></code></p></td>
<td><p>If set, only read VCF records within the specified range. The format is one of &lt;sequence_name&gt;, &lt;sequence_name&gt;:&lt;start&gt;-&lt;end&gt;, &lt;sequence_name&gt;:&lt;pos&gt;+&lt;length&gt; or
&lt;sequence_name&gt;:&lt;pos&gt;~&lt;padding&gt;</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 5%" />
<col style="width: 19%" />
<col style="width: 76%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Filtering</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--keep-filter=STRING</span></code></p></td>
<td><p>Keep the specified FILTER tag. May be specified 0 or more times, or as a comma separated list.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--keep-format=STRING</span></code></p></td>
<td><p>Keep the specified FORMAT field. May be specified 0 or more times, or as a comma separated list.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--keep-info=STRING</span></code></p></td>
<td><p>Keep the specified INFO tag. May be specified 0 or more times, or as a comma separated list.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--keep-sample=STRING|FILE</span></code></p></td>
<td><p>File containing sample IDs to keep, or a literal sample name. May be specified 0 or more times, or as a comma separated list.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--remove-filter=STRING</span></code></p></td>
<td><p>Remove the specified FILTER tag. May be specified 0 or more times, or as a comma separated list.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--remove-filters</span></code></p></td>
<td><p>Remove all FILTER tags.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--remove-format=STRING</span></code></p></td>
<td><p>Remove the specified FORMAT field. May be specified 0 or more times, or as a comma separated list.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--remove-ids</span></code></p></td>
<td><p>Remove the contents of the ID field.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--remove-info=STRING</span></code></p></td>
<td><p>Remove the specified INFO tag. May be specified 0 or more times, or as a comma separated list.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--remove-infos</span></code></p></td>
<td><p>Remove all INFO tags.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--remove-qual</span></code></p></td>
<td><p>Remove the QUAL field.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--remove-sample=STRING|FILE</span></code></p></td>
<td><p>File containing sample IDs to remove, or a literal sample name. May be specified 0 or more times, or as a comma separated list.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--remove-samples</span></code></p></td>
<td><p>Remove all samples.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 7%" />
<col style="width: 24%" />
<col style="width: 69%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Utility</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-h</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--help</span></code></p></td>
<td><p>Print help on command-line flag usage.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-Z</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-gzip</span></code></p></td>
<td><p>Do not gzip the output.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-header</span></code></p></td>
<td><p>Prevent VCF header from being written.</p></td>
</tr>
</tbody>
</table>
<p><strong>Usage:</strong></p>
<p>Use the <code class="docutils literal notranslate"><span class="pre">vcfsubset</span></code> command to produce a smaller copy of an original VCF
file containing only the columns and information desired. For example,
to produce a VCF containing only the information for one sample from a
multiple sample VCF file use the <code class="docutils literal notranslate"><span class="pre">--keep-sample</span></code> flag to specify the
sample to keep. The various <code class="docutils literal notranslate"><span class="pre">--keep</span></code> and <code class="docutils literal notranslate"><span class="pre">--remove</span></code> options can either be
specified multiple times or with comma separated lists, for example,
<code class="docutils literal notranslate"><span class="pre">--keep-format</span> <span class="pre">GT</span> <span class="pre">--keep-format</span> <span class="pre">DP</span></code> is equivalent to <code class="docutils literal notranslate"><span class="pre">–keep-format</span> <span class="pre">GT,DP</span></code>.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#snp"><span class="std std-ref">snp</span></a>,
<a class="reference internal" href="#family"><span class="std std-ref">family</span></a>,
<a class="reference internal" href="#somatic"><span class="std std-ref">somatic</span></a>,
<a class="reference internal" href="#population"><span class="std std-ref">population</span></a>,
<a class="reference internal" href="#vcffilter"><span class="std std-ref">vcffilter</span></a>,
<a class="reference internal" href="#vcfannotate"><span class="std std-ref">vcfannotate</span></a></p>
</div>
</div>
<div class="section" id="vcf2rocplot">
<h3>vcf2rocplot<a class="headerlink" href="#vcf2rocplot" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>Produce rocplot compatible ROC data files from vcfeval annotated
VCFs. The primary use cases for this command are to produce aggregate
ROCs from several independent <code class="docutils literal notranslate"><span class="pre">vcfeval</span></code> evaluation runs, and to
generate ROCs with respect to different criteria than were used during
the initial <code class="docutils literal notranslate"><span class="pre">vcfeval</span></code> evaluation.</p>
<p><strong>Syntax:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg vcf2rocplot [OPTION]... -o DIR FILE+
</pre></div>
</div>
<p>Create an aggregate ROC from evaluations of several independent samples:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg vcfeval -b goldstandard.vcf.gz -c snps.vcf.gz -t HUMAN_reference \
  --sample daughter1 -f AVR -o eval -m annotate
$ rtg vcfeval -b goldstandard.vcf.gz -c snps.vcf.gz -t HUMAN_reference \
  --sample daughter2 -f AVR -o eval -m annotate
$ rtg vcfeval -b goldstandard.vcf.gz -c snps.vcf.gz -t HUMAN_reference \
  --sample son2 -f AVR -o eval -m annotate
$ rtg vcf2rocplot -o eval_family -f AVR \
  eval_{daughter1,daughter2,son1}/{baseline,calls}.vcf.gz
$ rtg rocplot eval_family/weighted_roc.tsv.gz \
  --png eval_family_roc.png
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<table class="docutils align-default">
<colgroup>
<col style="width: 4%" />
<col style="width: 15%" />
<col style="width: 81%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>File Input/Output</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--bed-regions=FILE</span></code></p></td>
<td><p>If set, only read VCF records that overlap the ranges contained in the specified BED file.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-o</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--output=DIR</span></code></p></td>
<td><p>Directory for output.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--region=REGION</span></code></p></td>
<td><p>If set, only read VCF records within the specified range. The format is one of &lt;sequence_name&gt;, &lt;sequence_name&gt;:&lt;start&gt;-&lt;end&gt;, &lt;sequence_name&gt;:&lt;pos&gt;+&lt;length&gt; or
&lt;sequence_name&gt;:&lt;pos&gt;~&lt;padding&gt;</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">FILE+</span></code></p></td>
<td><p>Input VCF files containing vcfeval annotations. Must be specified 1 or more times.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 4%" />
<col style="width: 15%" />
<col style="width: 81%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Reporting</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--at-precision=FLOAT</span></code></p></td>
<td><p>Output summary statistics where precision &gt;= supplied value (Default is to summarize at maximum F-measure)</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--at-sensitivity=FLOAT</span></code></p></td>
<td><p>Output summary statistics where sensitivity &gt;= supplied value (Default is to summarize at maximum F-measure)</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--roc-expr=STRING</span></code></p></td>
<td><p>Output ROC file for variants matching custom JavaScript expression. Use the form &lt;LABEL&gt;=&lt;EXPRESSION&gt;. May be specified 0 or more times.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--roc-regions=STRING</span></code></p></td>
<td><p>Output ROC file for variants overlapping custom regions supplied in BED file. Use the form &lt;LABEL&gt;=&lt;FILENAME&gt;. May be specified 0 or more times.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--roc-subset=STRING</span></code></p></td>
<td><p>Output ROC file for preset variant subset. Allowed values are [hom, het, snp, non-snp, mnp, indel]. May be specified 0 or more times, or as a comma separated
list.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-O</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--sort-order=STRING</span></code></p></td>
<td><p>The order in which to sort the ROC scores so that <code class="docutils literal notranslate"><span class="pre">good</span></code> scores come before <code class="docutils literal notranslate"><span class="pre">bad</span></code> scores. Allowed values are [ascending, descending] (Default is descending)</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-f</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--vcf-score-field=STRING</span></code></p></td>
<td><p>The name of the VCF FORMAT field to use as the ROC score. Also valid are <code class="docutils literal notranslate"><span class="pre">QUAL</span></code>, <code class="docutils literal notranslate"><span class="pre">INFO.&lt;name&gt;</span></code> or <code class="docutils literal notranslate"><span class="pre">FORMAT.&lt;name&gt;</span></code> to select the named VCF FORMAT or INFO
field (Default is GQ)</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 7%" />
<col style="width: 25%" />
<col style="width: 68%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Utility</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-h</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--help</span></code></p></td>
<td><p>Print help on command-line flag usage.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-Z</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-gzip</span></code></p></td>
<td><p>Do not gzip the output.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-T</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--threads=INT</span></code></p></td>
<td><p>Number of threads (Default is the number of available cores)</p></td>
</tr>
</tbody>
</table>
<p><strong>Usage:</strong></p>
<p>While the ROC outputs generated by <code class="docutils literal notranslate"><span class="pre">vcfeval</span></code> are sufficient for many
scenarios, there are some situations where it is useful to regenerate
ROC files from one or more existing vcfeval outputs.</p>
<p>One such situation is when evaluating caller accuracy across a cohort of
samples where the number of variants per individual sample is
low. Individual sample ROC curves are fairly uninformative with regard
to overall accuracy or where to place suitable filter thresholds. An ROC
curve from the combined evaluations provides a much better indication of
overall caller accuracy.</p>
<p>Another use case for generating ROC files from an existing <code class="docutils literal notranslate"><span class="pre">vcfeval</span></code>
run is to look at alternative scoring methods or stratifications without
having to execute the time-consuming variant matching stage implied by a
new <code class="docutils literal notranslate"><span class="pre">vcfeval</span></code> run.</p>
<p>The prerequisite for using <code class="docutils literal notranslate"><span class="pre">vcf2rocplot</span></code> is that <code class="docutils literal notranslate"><span class="pre">vcfeval</span></code> must
have been run in “annotation” mode (i.e. via <code class="docutils literal notranslate"><span class="pre">--output-mode=annotate</span></code>)
so that the output VCF files contain sufficient annotations regarding
variant classification status. It is important that <code class="docutils literal notranslate"><span class="pre">vcf2rocplot</span></code> be
provided with both annotated baseline and call VCFs in order to produce
correct outputs.</p>
<p>The operation of the various score field selection and ROC
stratification flags works the same as when running <code class="docutils literal notranslate"><span class="pre">vcfeval</span></code>.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#rocplot"><span class="std std-ref">rocplot</span></a>,
<a class="reference internal" href="#vcfeval"><span class="std std-ref">vcfeval</span></a></p>
</div>
</div>
<div class="section" id="svdecompose">
<h3>svdecompose<a class="headerlink" href="#svdecompose" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>Split composite structural variants into a breakend representation.</p>
<p><strong>Syntax:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg svdecompose [OPTION]... -i FILE -o FILE
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<table class="docutils align-default">
<colgroup>
<col style="width: 7%" />
<col style="width: 17%" />
<col style="width: 75%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>File Input/Output</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-i</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--input=FILE</span></code></p></td>
<td><p>VCF file containing variants to filter. Use ‘-‘ to read from standard input.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-o</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--output=FILE</span></code></p></td>
<td><p>Output VCF file name. Use ‘-‘ to write to standard output.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 7%" />
<col style="width: 17%" />
<col style="width: 75%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Utility</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-h</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--help</span></code></p></td>
<td><p>Print help on command-line flag usage.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-Z</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-gzip</span></code></p></td>
<td><p>Do not gzip the output.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-header</span></code></p></td>
<td><p>Prevent VCF header from being written.</p></td>
</tr>
</tbody>
</table>
<p><strong>Usage:</strong></p>
<p>The <code class="docutils literal notranslate"><span class="pre">svdecompose</span></code> command is applied to a VCF containing structural
variants and converts deletion, insertion, inversion, and tandem
duplications with <code class="docutils literal notranslate"><span class="pre">SVTYPE</span></code> of <code class="docutils literal notranslate"><span class="pre">DEL</span></code>, <code class="docutils literal notranslate"><span class="pre">INS</span></code>, <code class="docutils literal notranslate"><span class="pre">INV</span></code>, and
<code class="docutils literal notranslate"><span class="pre">DUP</span></code>, respectively, into corresponding breakend events with
<code class="docutils literal notranslate"><span class="pre">SVTYPE=BND</span></code>.  <code class="docutils literal notranslate"><span class="pre">svdecompose</span></code> will also decompose sequence-resolved
insertions and deletions greater than <code class="docutils literal notranslate"><span class="pre">--min-indel-length</span></code> into
breakend representation. Records of others types are passed through
without modification.</p>
<p>This operation can be useful for the purposes of reducing output from
various structural variant callers to a common representation to
better facilitate comparison with the <code class="docutils literal notranslate"><span class="pre">bndeval</span></code> command.</p>
<p>For insertions, <code class="docutils literal notranslate"><span class="pre">svdecompose</span></code> will represent the insertion as
breakends between the reference and a “virtual haplotype”, where for
example, contig “&lt;INS_A&gt;” represents the destination of all insertions
made on chromosome A. So if another caller produced a similar insertion
event (in position and/or length), the break end versions will also be
nearby on the virtual contig. For the following insertions:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>1  54712   .     T  TTTTTTTTTCTTTCTTTCTTTCTTTCTTTCTTTCTTTCTTTCTTTCTTTCTTTC  .  .  .
1  934144  I_7   C  CGGAGGGGAGGGCGCGGAGCGGAGG                               .  .  .
1  934144  I_22  C  CGGAGGGGAGGGCGCGGAGCGGAGGGGAGGGCGCGGAGCGGAGG            .  .  .
</pre></div>
</div>
<p>each insertion gets two breakends like this:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>1  54712   .     T  T[&lt;INS_1&gt;:54712[   .  .  SVTYPE=BND;CIPOS=0,0
1  54712   .     T  ]&lt;INS_1&gt;:54765]C   .  .  SVTYPE=BND;CIPOS=0,0
1  934144  I_7   C  C[&lt;INS_1&gt;:934144[  .  .  SVTYPE=BND;CIPOS=0,0
1  934144  I_22  C  C[&lt;INS_1&gt;:934144[  .  .  SVTYPE=BND;CIPOS=0,0
1  934144  I_7   C  ]&lt;INS_1&gt;:934168]G  .  .  SVTYPE=BND;CIPOS=0,0
1  934144  I_22  C  ]&lt;INS_1&gt;:934187]G  .  .  SVTYPE=BND;CIPOS=0,0
</pre></div>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#bndeval"><span class="std std-ref">bndeval</span></a></p>
</div>
</div>
<div class="section" id="bndeval">
<h3>bndeval<a class="headerlink" href="#bndeval" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>Evaluate called breakends for agreement with a baseline breakend set.
Outputs a weighted ROC file which can be viewed with <code class="docutils literal notranslate"><span class="pre">rtg</span> <span class="pre">rocplot</span></code>
and VCF files containing false positives (called breakends not matched
in the baseline), false negatives (baseline breakends not matched in
the call set), and true positives (breakends that match between the
baseline and calls).</p>
<p><strong>Syntax:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg bndeval [OPTION]... -b FILE -c FILE -o DIR
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<table class="docutils align-default">
<colgroup>
<col style="width: 4%" />
<col style="width: 15%" />
<col style="width: 81%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>File Input/Output</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-b</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--baseline=FILE</span></code></p></td>
<td><p>VCF file containing baseline variants.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--bed-regions=FILE</span></code></p></td>
<td><p>If set, only read VCF records that overlap the ranges contained in the specified BED file.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-c</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--calls=FILE</span></code></p></td>
<td><p>VCF file containing called variants.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-o</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--output=DIR</span></code></p></td>
<td><p>Directory for output.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--region=REGION</span></code></p></td>
<td><p>If set, only read VCF records within the specified range. The format is one of &lt;sequence_name&gt;, &lt;sequence_name&gt;:&lt;start&gt;-&lt;end&gt;, &lt;sequence_name&gt;:&lt;pos&gt;+&lt;length&gt; or
&lt;sequence_name&gt;:&lt;pos&gt;~&lt;padding&gt;</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 5%" />
<col style="width: 19%" />
<col style="width: 75%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Filtering</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--all-records</span></code></p></td>
<td><p>Use all records regardless of FILTER status (Default is to only process records where FILTER is “.” or “PASS”)</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--bidirectional</span></code></p></td>
<td><p>If set, allow matches between flipped breakends.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--tolerance=INT</span></code></p></td>
<td><p>Positional tolerance for breakend matching (Default is 100)</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 4%" />
<col style="width: 15%" />
<col style="width: 81%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Reporting</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-roc</span></code></p></td>
<td><p>Do not produce ROCs.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-m</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--output-mode=STRING</span></code></p></td>
<td><p>Output reporting mode. Allowed values are [split, annotate] (Default is split)</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-O</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--sort-order=STRING</span></code></p></td>
<td><p>The order in which to sort the ROC scores so that <code class="docutils literal notranslate"><span class="pre">good</span></code> scores come before <code class="docutils literal notranslate"><span class="pre">bad</span></code> scores. Allowed values are [ascending, descending] (Default is descending)</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-f</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--vcf-score-field=STRING</span></code></p></td>
<td><p>The name of the VCF FORMAT field to use as the ROC score. Also valid are <code class="docutils literal notranslate"><span class="pre">QUAL</span></code>, <code class="docutils literal notranslate"><span class="pre">INFO.&lt;name&gt;</span></code> or <code class="docutils literal notranslate"><span class="pre">FORMAT.&lt;name&gt;</span></code> to select the named VCF FORMAT or INFO
field (Default is INFO.DP)</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 7%" />
<col style="width: 25%" />
<col style="width: 68%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Utility</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-h</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--help</span></code></p></td>
<td><p>Print help on command-line flag usage.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">-Z</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--no-gzip</span></code></p></td>
<td><p>Do not gzip the output.</p></td>
</tr>
</tbody>
</table>
<p><strong>Usage:</strong></p>
<p>The <code class="docutils literal notranslate"><span class="pre">bndeval</span></code> command operates on VCF files containing breakends such
as those produced by the <code class="docutils literal notranslate"><span class="pre">discord</span></code> command.  In particular, it
considers records having the breakend structural variant type
(<code class="docutils literal notranslate"><span class="pre">SVTYPE=BND</span></code>) as defined in the VCF specification.  Other types of
record are ignored, but the <code class="docutils literal notranslate"><span class="pre">svdecompose</span></code> command can be applied
beforehand to split certain other structural variants (e.g., <code class="docutils literal notranslate"><span class="pre">INV</span></code> and
<code class="docutils literal notranslate"><span class="pre">DEL</span></code>) or sequence-resolved insertions and deletions into constituent
breakend events.</p>
<p>The input and output requirements of <code class="docutils literal notranslate"><span class="pre">bndeval</span></code> are broadly similar
to the <code class="docutils literal notranslate"><span class="pre">vcfeval</span></code> command.  The primary inputs to <code class="docutils literal notranslate"><span class="pre">bndeval</span></code> are a
truth/baseline VCF containing expected breakends, and a query/call VCF
containing the called breakends.  Evaluation can be restricted to
particular regions by specifying a BED file.</p>
<p>The regions contained in the evaluation regions BED file are intersected
with the breakend records contained in the truth VCF in order to obtain a
list of <em>truth breakend regions</em>. An evaluation region is included if there
is any overlapping truth VCF record (no attempt is made to look at the
degree of overlap).  Thus by supplying either evaluation regions
corresponding to targeted regions or larger gene-level regions
<code class="docutils literal notranslate"><span class="pre">bndeval</span></code> can be used to evaluate at different levels of granularity.</p>
<p>Similarly, the evaluation regions are intersected with the breakend records
records contained in the calls VCF to obtain <em>called breakend regions</em>.</p>
<p>The <em>truth breakend regions</em> are then intersected with the <em>called breakend
regions</em> to obtain TP/FP/FN metrics.  The intersection supports a
user-selectable tolerance in position.  Further, be default, a breakend
must occur in the same orientation to be considered a match, but this
constraint can be relaxed by supplying the <code class="docutils literal notranslate"><span class="pre">--bidirectional</span></code> command
line option.</p>
<div class="section" id="bndeval-outputs">
<h4>bndeval outputs<a class="headerlink" href="#bndeval-outputs" title="Permalink to this headline">¶</a></h4>
<p>Once complete, <code class="docutils literal notranslate"><span class="pre">bndeval</span></code> command produces summary statistics and the
following primary result files in the output directory:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">weighted_roc.tsv.gz</span></code> - contains ROC data that can be plotted
with <code class="docutils literal notranslate"><span class="pre">rocplot</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">baseline.bed.gz</span></code> contains the <em>truth breakend regions</em>, where each BED
record contains the region status as <code class="docutils literal notranslate"><span class="pre">TP</span></code> or <code class="docutils literal notranslate"><span class="pre">FN</span></code>, the <code class="docutils literal notranslate"><span class="pre">SVTYPE</span></code>,
and the span of the original truth VCF record.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">calls.bed.gz</span></code> contains the <em>called breakend regions</em>, where each BED
record contains the region status as <code class="docutils literal notranslate"><span class="pre">TP</span></code> or <code class="docutils literal notranslate"><span class="pre">FP</span></code>, the <code class="docutils literal notranslate"><span class="pre">SVTYPE</span></code>,
the span of the original calls VCF record, and the score value used
for ranking in the ROC plot.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">summary.txt</span></code> contains the same summary statistics printed to
standard output.</p></li>
</ul>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#discord"><span class="std std-ref">discord</span></a>,
<a class="reference internal" href="#svdecompose"><span class="std std-ref">svdecompose</span></a>,
<a class="reference internal" href="#vcfeval"><span class="std std-ref">vcfeval</span></a>,
<a class="reference internal" href="#rocplot"><span class="std std-ref">rocplot</span></a></p>
</div>
</div>
</div>
<div class="section" id="pedfilter">
<h3>pedfilter<a class="headerlink" href="#pedfilter" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>Filter and convert a pedigree file.</p>
<p><strong>Syntax:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg pedfilter [OPTION]... FILE
</pre></div>
</div>
<p><strong>Example:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg pedfilter --remove-parentage mypedigree.ped
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<table class="docutils align-default">
<colgroup>
<col style="width: 6%" />
<col style="width: 18%" />
<col style="width: 76%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>File Input/Output</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">FILE</span></code></p></td>
<td><p>The pedigree file to process, may be PED or VCF, use ‘-‘ to read from stdin.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 5%" />
<col style="width: 17%" />
<col style="width: 77%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Filtering</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--keep-family=STRING</span></code></p></td>
<td><p>Keep only individuals with the specified family ID. May be specified 0 or more times, or as a comma separated list.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--keep-ids=STRING</span></code></p></td>
<td><p>Keep only individuals with the specified ID. May be specified 0 or more times, or as a comma separated list.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--keep-primary</span></code></p></td>
<td><p>Keep only primary individuals (those with a PED individual line / VCF sample column)</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--remove-parentage</span></code></p></td>
<td><p>Remove all parent-child relationship information.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 6%" />
<col style="width: 18%" />
<col style="width: 76%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Reporting</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--vcf</span></code></p></td>
<td><p>Output pedigree in in the form of a VCF header rather than PED.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 6%" />
<col style="width: 18%" />
<col style="width: 76%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Utility</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-h</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--help</span></code></p></td>
<td><p>Print help on command-line flag usage.</p></td>
</tr>
</tbody>
</table>
<p><strong>Usage:</strong></p>
<p>The <code class="docutils literal notranslate"><span class="pre">pedfilter</span></code> command can be used to perform manipulations on pedigree
information and convert pedigree information between PED and VCF header
format.  For more information about the PED file format see <a class="reference internal" href="appendix.html#pedigree-ped-input-file-format"><span class="std std-ref">Pedigree PED input file format</span></a>.</p>
<p>The VCF files output by the <code class="docutils literal notranslate"><span class="pre">family</span></code> and <code class="docutils literal notranslate"><span class="pre">population</span></code> commands contain
full pedigree information represented as VCF header lines, and the
<code class="docutils literal notranslate"><span class="pre">pedfilter</span></code> command allows this information to be extracted in PED
format.</p>
<p>This command produces the pedigree output on standard output, which can
be redirected to a file or another pipeline command as required.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#family"><span class="std std-ref">family</span></a>,
<a class="reference internal" href="#population"><span class="std std-ref">population</span></a>,
<a class="reference internal" href="#mendelian"><span class="std std-ref">mendelian</span></a>,
<a class="reference internal" href="#pedstats"><span class="std std-ref">pedstats</span></a></p>
</div>
</div>
<div class="section" id="pedstats">
<h3>pedstats<a class="headerlink" href="#pedstats" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>Output information from pedigree files of various formats.</p>
<p><strong>Syntax:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg pedstats [OPTION]... FILE
</pre></div>
</div>
<p><strong>Example:</strong></p>
<p>For a summary of pedigree information:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg pedstats ceph_pedigree.ped

Pedigree file: /data/ceph/ceph_pedigree.ped

Total samples:               17
Primary samples:             17
Male samples:                 9
Female samples:               8
Afflicted samples:            0
Founder samples:              4
Parent-child relationships:  26
Other relationships:          0
Families:                     3
</pre></div>
</div>
<p>To output a list of all founders:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg pedstats --founder-ids ceph_pedigree.ped
NA12889
NA12890
NA12891
NA12892
</pre></div>
</div>
<p>For quick pedigree visualization using Graphviz and ImageMagick, use a
command-line such as:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ dot -Tpng &lt;(rtg pedstats --dot &quot;A Title&quot; mypedigree.ped) | display -
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<table class="docutils align-default">
<colgroup>
<col style="width: 7%" />
<col style="width: 18%" />
<col style="width: 75%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>File Input/Output</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">FILE</span></code></p></td>
<td><p>The pedigree file to process, may be PED or VCF, use ‘-‘ to read from stdin.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 4%" />
<col style="width: 13%" />
<col style="width: 82%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Reporting</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-d</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--delimiter=STRING</span></code></p></td>
<td><p>Output id lists using this separator (Default is \n)</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--dot=STRING</span></code></p></td>
<td><p>Output pedigree in Graphviz format, using the supplied text as a title.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--families</span></code></p></td>
<td><p>Output information about family structures.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--female-ids</span></code></p></td>
<td><p>Output ids of all females.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--founder-ids</span></code></p></td>
<td><p>Output ids of all founders.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--male-ids</span></code></p></td>
<td><p>Output ids of all males.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--maternal-ids</span></code></p></td>
<td><p>Output ids of maternal individuals.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--paternal-ids</span></code></p></td>
<td><p>Output ids of paternal individuals.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--primary-ids</span></code></p></td>
<td><p>Output ids of all primary individuals.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--simple-dot</span></code></p></td>
<td><p>When outputting Graphviz format, use a layout that looks less like a traditional pedigree diagram but works better with large complex pedigrees.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 7%" />
<col style="width: 18%" />
<col style="width: 75%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Utility</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-h</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--help</span></code></p></td>
<td><p>Print help on command-line flag usage.</p></td>
</tr>
</tbody>
</table>
<p><strong>Usage:</strong></p>
<p>This command is used to show pedigree summary statistics or select
groups of individual IDs.</p>
<p>When using <code class="docutils literal notranslate"><span class="pre">pedstats</span></code> to output a list of sample IDs, the default is
to print one ID per line. Depending on subsequent use, it may be
convenient to use a different separator between output IDs. For example,
with comma separated output it is possible to directly use the results
as an argument to <code class="docutils literal notranslate"><span class="pre">vcfsubset</span></code>:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg vcfsubset -i pedigree-calls.vcf.gz -o family1.vcf.gz \
    --keep-samples &lt;(rtg pedstats -d , --founder-ids ceph_pedigree.ped)
</pre></div>
</div>
<p>In addition, <code class="docutils literal notranslate"><span class="pre">pedstats</span></code> can be used to generate a simple pedigree
visualization, using the well-known Graphviz graphics drawing package,
which can be saved to PNG or PDF.  For example, with the following
<code class="docutils literal notranslate"><span class="pre">chinese-trio.ped</span></code>:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>#PED format pedigree
#
#fam-id/ind-id/pat-id/mat-id: 0=unknown
#sex: 1=male; 2=female; 0=unknown
#phenotype: -9=missing, 0=missing; 1=unaffected; 2=affected
#
#fam-id ind-id  pat-id  mat-id  sex     phen
0       NA24631 NA24694 NA24695 1       0
0       NA24694 0       0       1       0
0       NA24695 0       0       2       0
</pre></div>
</div>
<p>We can visualize the pedigree with:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ dot -Tpng &lt;(rtg pedstats --dot &quot;Chinese Trio&quot; chinese-trio.ped) -o chinese-trio.png
</pre></div>
</div>
<p>This will create a PNG image that can be displayed in any image viewing
tool and contains the pedigree structure as shown below.</p>
<img alt="_images/chinese-trio.png" src="_images/chinese-trio.png" />
<p>For more information about the PED file format see <a class="reference internal" href="appendix.html#pedigree-ped-input-file-format"><span class="std std-ref">Pedigree PED input file format</span></a>.</p>
<p>The VCF files output by the RTG pedigree-aware variant calling commands
contain full pedigree information represented as VCF header lines, and
the <code class="docutils literal notranslate"><span class="pre">pedstats</span></code> command can also take these VCFs as input. For example,
given a VCF produced by the <code class="docutils literal notranslate"><span class="pre">population</span></code> command after calling the
CEPH-1463 pedigree:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ dot -Tpng &lt;(rtg pedstats --dot &quot;CEPH 1463&quot; population-ceph-calls.vcf.gz) -o ceph-1463.png
</pre></div>
</div>
<p>Would produce the following pedigree directly from the VCF:</p>
<img alt="_images/ceph-1463.png" src="_images/ceph-1463.png" />
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Graphviz is provided directly via many operating system
package managers, and can also be downloaded from their web site:
<a class="reference external" href="https://www.graphviz.org/">https://www.graphviz.org/</a></p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#family"><span class="std std-ref">family</span></a>,
<a class="reference internal" href="#population"><span class="std std-ref">population</span></a>,
<a class="reference internal" href="#pedfilter"><span class="std std-ref">pedfilter</span></a>,
<a class="reference internal" href="#vcfsubset"><span class="std std-ref">vcfsubset</span></a></p>
</div>
</div>
<div class="section" id="rocplot">
<h3>rocplot<a class="headerlink" href="#rocplot" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>Plot ROC curves from <code class="docutils literal notranslate"><span class="pre">readsimeval</span></code> and <code class="docutils literal notranslate"><span class="pre">vcfeval</span></code> ROC data files, either
to an image, or using an interactive GUI.</p>
<p><strong>Syntax:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg rocplot [OPTION]... FILE+
</pre></div>
</div>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg rocplot [OPTION]... --curve STRING
</pre></div>
</div>
<p><strong>Example:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg rocplot eval/weighted_roc.tsv.gz
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<table class="docutils align-default">
<colgroup>
<col style="width: 5%" />
<col style="width: 19%" />
<col style="width: 75%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>File Input/Output</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--curve=STRING</span></code></p></td>
<td><p>ROC data file with title optionally specified (path[=title]). May be specified 0 or more times.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--png=FILE</span></code></p></td>
<td><p>If set, output a PNG image to the given file.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--svg=FILE</span></code></p></td>
<td><p>If set, output a SVG image to the given file.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--zoom=STRING</span></code></p></td>
<td><p>Show a zoomed view with the given coordinates, supplied in the form &lt;xmax&gt;,&lt;ymax&gt; or &lt;xmin&gt;,&lt;ymin&gt;,&lt;xmax&gt;,&lt;ymax&gt;</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">FILE+</span></code></p></td>
<td><p>ROC data file. May be specified 0 or more times.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 4%" />
<col style="width: 15%" />
<col style="width: 81%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Reporting</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--cmd=FILE</span></code></p></td>
<td><p>If set, print rocplot command used in previously saved image.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--hide-sidepane</span></code></p></td>
<td><p>If set, hide the side pane from the GUI on startup.</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--interpolate</span></code></p></td>
<td><p>If set, interpolate curves at regular intervals.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--line-width=INT</span></code></p></td>
<td><p>Sets the plot line width (Default is 2)</p></td>
</tr>
<tr class="row-even"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--palette=STRING</span></code></p></td>
<td><p>Name of color palette to use. Allowed values are [blind_13, blind_15, blind_8, brewer_accent, brewer_dark2, brewer_paired, brewer_pastel1, brewer_pastel2,
brewer_set1, brewer_set2, brewer_set3, classic] (Default is classic)</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--plain</span></code></p></td>
<td><p>If set, use a plain plot style.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-P</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--precision-sensitivity</span></code></p></td>
<td><p>If set, plot precision vs sensitivity rather than ROC.</p></td>
</tr>
<tr class="row-odd"><td></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--scores</span></code></p></td>
<td><p>If set, show scores on the plot.</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-t</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--title=STRING</span></code></p></td>
<td><p>Title for the plot.</p></td>
</tr>
</tbody>
</table>
<table class="docutils align-default">
<colgroup>
<col style="width: 7%" />
<col style="width: 24%" />
<col style="width: 69%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" colspan="3"><p>Utility</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">-h</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--help</span></code></p></td>
<td><p>Print help on command-line flag usage.</p></td>
</tr>
</tbody>
</table>
<p><strong>Usage:</strong></p>
<p>Used to produce ROC plots from the ROC files produced by
<code class="docutils literal notranslate"><span class="pre">readsimeval</span></code>, <code class="docutils literal notranslate"><span class="pre">bndeval</span></code> and <code class="docutils literal notranslate"><span class="pre">vcfeval</span></code>. By default this opens the
ROC plots in an interactive viewer. On a system with only console access
the plot can be saved directly to an image file using the either the
<code class="docutils literal notranslate"><span class="pre">--png</span></code> or <code class="docutils literal notranslate"><span class="pre">--svg</span></code> parameter.</p>
<p>ROC data files may be specified either as direct file arguments to the
command, or via the <code class="docutils literal notranslate"><span class="pre">--curve</span></code> flag. The former method is useful when
selecting files using shell wild card globbing, and the latter method
allows specifying a custom title for each curve, so use whichever method
is most convenient.</p>
<p>Strictly speaking, a true ROC curve should use <em>rates</em> rather than
absolute numbers on the X and Y axes (e.g. True Positive / Total
Positives rather than True Positives on the Y, and False Positive /
Total Negatives on the X axis). However, there are a couple of
difficulties involved with computing these rates with variant calling
datasets. Firstly, the truth sets do not include any indication of
the set of negatives (the closest we may get is in the cases of truth
sets which contain a set of confidence regions, where it can be assumed
that no other variants may be present inside the specified regions);
secondly even with knowledge of negative regions, how do you count the
set of possible negative calls, when a call could occupy multiple
reference bases, or even (in the case of insertions) zero reference
bases. It is conceptually even possible to have a call-set contain more
false positives than there are reference bases. For this reason the ROC
curves are plotted using the absolute counts.</p>
<p>Precision/sensitivity (also known as precision/recall) curves are
another popular means of visualizing call-set accuracy, and these
metrics also do not require a count of Total Negatives and so cause no
particular difficulty to plot. Precision/sensitivity graphs can be
selected from the command line via the <code class="docutils literal notranslate"><span class="pre">--precision-sensitivity</span></code> flag,
or may be interactively selected in the GUI.</p>
<p>An interesting result of ROC analysis is that although there may be few
data points on an ROC graph, it is possible to construct a filtered
dataset corresponding to any point that lies on a straight line between
two points on the graph. (For example, using threshold A for 25% of the
variants and threshold B for 75% of the variants would result in
accuracy that is 75% of the way between the points corresponding to
thresholds A and B on the ROC plot). So in a sense it is meaningful to
connect points on an ROC graph with straight lines. However, for
precision/sensitivity graphs, it’s incorrect to connect adjacent points
with a straight line, as this does not correspond to achievable accuracy
on the ROC convex hull and can over-estimate the accuracy. Instead, we
can plot appropriately interpolated values with the <code class="docutils literal notranslate"><span class="pre">--interpolate</span></code>
option.</p>
<p>The default ROC graphs include some flourishes such as background
gradients and axes drop shadows, these can be disabled via the
<code class="docutils literal notranslate"><span class="pre">--plain</span></code> parameter.  Alternative preset color palettes for the curve
colors may be selected with the <code class="docutils literal notranslate"><span class="pre">--palette</span></code> parameter, and in
particular some palettes are more color-blind friendly than the default
palette. In addition, PNG images saved by <code class="docutils literal notranslate"><span class="pre">rocplot</span></code> include metadata
indicating the graph configuration that may be useful when recreating
graphs. This metadata can be displayed (when present) via the <code class="docutils literal notranslate"><span class="pre">--cmd</span></code>
parameter.</p>
<div class="section" id="interactive-gui">
<h4>Interactive GUI<a class="headerlink" href="#interactive-gui" title="Permalink to this headline">¶</a></h4>
<p>The following image shows the <code class="docutils literal notranslate"><span class="pre">rocplot</span></code> GUI with an example ROC plot :</p>
<img alt="_images/rocplot_roc.png" src="_images/rocplot_roc.png" />
<p>Similarly, here is an example precision/sensitivity plot:</p>
<img alt="_images/rocplot_ps.png" src="_images/rocplot_ps.png" />
<p>Some quick tips for the interactive GUI:</p>
<ul class="simple">
<li><p>Select regions within the graph to zoom in. Right click within the
graph area to bring up a context menu that allows undoing the zoom one
level at a time, or resetting the zoom to the default.</p></li>
<li><p>The graph right click menu also allows exporting the image as PNG or
SVG. (The saved image does not include the RTG banner).</p></li>
<li><p>Click on a spot in the graph to show the equivalent accuracy metrics
for that location in the status bar. Clicking to the left or below the
axes will remove the cross-hair. Note that sensitivity depends on the
baseline total number of variants being correct. If for example the
ROC curve corresponds to evaluating an exome call-set against a
whole-genome baseline, this number will be inaccurate.</p></li>
<li><p>A secondary cross-hair is also available by holding down shift when
placing (or removing) the cross-hair. When two cross-hairs are placed
or moved, metrics in the status bar indicate the difference between
the two positions.</p></li>
<li><p>Additional ROC data files can be loaded by clicking on the “Open…”
button, and multiple ROC data files within a directory can be loaded
at once using multi-select. Alternatively, you may use Drag and Drop
from your file browser to drop ROC data files into either the graph
area or the right hand ROC curve widget area.</p></li>
<li><p>The “Cmd” button will open a message window that contains a
command-line equivalent to the currently displayed set of curves. This
command-line may be copy-pasted, providing an easy way to replicate
the current set of curves in another session, generate a curve in a
script, or share with a colleague.</p></li>
<li><p>There is a drop down that allows for switching between ROC and
precision/sensitivity graph types.</p></li>
</ul>
<p>Each curve in the GUI has a customization widget on the right hand
side of the window that allows several operations:</p>
<ul class="simple">
<li><p>Rename the title used for the curve via the editable text.</p></li>
<li><p>Temporarily hide/show the curve via selection checkbox.</p></li>
<li><p>Reorder curves via drag and drop using the colored handle on the left.</p></li>
<li><p>Right click within the ROC widget area to bring up a context menu that
allows permanently removing that curve, or customizing the color used
for the curve</p></li>
<li><p>Each curve has a slider to simulate the effect of applying a threshold
on the scoring attribute. If the “show scores” option is set, this
provides an easy way to select appropriate filter threshold values,
which you might apply to variant sets using <code class="docutils literal notranslate"><span class="pre">rtg</span> <span class="pre">vcffilter</span></code> or
similar VCF filtering tools.</p></li>
</ul>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>For definitions of the terminology used when evaluating caller
accuracy, see:
<a class="reference external" href="https://en.wikipedia.org/wiki/Receiver_operating_characteristic">https://en.wikipedia.org/wiki/Receiver_operating_characteristic</a>
and <a class="reference external" href="https://en.wikipedia.org/wiki/Sensitivity_and_specificity">https://en.wikipedia.org/wiki/Sensitivity_and_specificity</a></p>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>For a description of the precision/sensitivity interpolation,
see: “The relationship between Precision-Recall and ROC
curves”, Davis, J., (2006),
<a class="reference external" href="https://dx.doi.org/10.1145/1143844.1143874">https://dx.doi.org/10.1145/1143844.1143874</a></p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#readsimeval"><span class="std std-ref">readsimeval</span></a>,
<a class="reference internal" href="#bndeval"><span class="std std-ref">bndeval</span></a>,
<a class="reference internal" href="#vcfeval"><span class="std std-ref">vcfeval</span></a></p>
</div>
</div>
</div>
<div class="section" id="version">
<h3>version<a class="headerlink" href="#version" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>The RTG version display utility.</p>
<p><strong>Syntax:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg version
</pre></div>
</div>
<p><strong>Example:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg version

Product: RTG Core 3.9
Core Version: 718f8317b7 (2018-05-29)
RAM: 25.0GB of 31.3GB RAM can be used by rtg (79%)
CPU: Defaulting to 4 of 4 available processors (100%)
JVM: Java HotSpot(TM) 64-Bit Server VM 1.8.0_161
License: Expires on 2019-05-20
Contact: support@realtimegenomics.com

Patents / Patents pending:
US: 7,640,256, 9,165,253, 13/129,329, 13/681,046, 13/681,215, 13/848,653, 13/925,704, 14/015,295, 13/971,654, 13/971,630, 14/564,810
UK: 1222923.3, 1222921.7, 1304502.6, 1311209.9, 1314888.7, 1314908.3
New Zealand: 626777, 626783, 615491, 614897, 614560
Australia: 2005255348, Singapore: 128254

Citation (variant calling):
John G. Cleary, Ross Braithwaite, Kurt Gaastra, Brian S. Hilbush, Stuart Inglis, Sean A. Irvine, Alan Jackson, Richard Littin, Sahar Nohzadeh-Malakshah, Mehul Rathod, David Ware, Len Trigg, and Francisco M. De La Vega. &quot;Joint Variant and De Novo Mutation Identification on Pedigrees from High-Throughput Sequencing Data.&quot; Journal of Computational Biology. June 2014, 21(6): 405-419. doi:10.1089/cmb.2014.0029.

Citation (vcfeval):
John G. Cleary, Ross Braithwaite, Kurt Gaastra, Brian S. Hilbush, Stuart Inglis, Sean A. Irvine, Alan Jackson, Richard Littin, Mehul Rathod, David Ware, Justin M. Zook, Len Trigg, and Francisco M. De La Vega. &quot;Comparing Variant Call Files for Performance Benchmarking of Next-Generation Sequencing Variant Calling Pipelines.&quot; bioRxiv, 2015. doi:10.1101/023754.

(c) Real Time Genomics, 2017
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<p>There are no options associated with the <code class="docutils literal notranslate"><span class="pre">version</span></code> command.</p>
<p><strong>Usage:</strong></p>
<p>Use the <code class="docutils literal notranslate"><span class="pre">version</span></code> command to display release and version information.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#help"><span class="std std-ref">help</span></a>,
<a class="reference internal" href="#license"><span class="std std-ref">license</span></a></p>
</div>
</div>
<div class="section" id="license">
<h3>license<a class="headerlink" href="#license" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>The RTG license display utility.</p>
<p><strong>Syntax:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg license
</pre></div>
</div>
<p><strong>Example:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg license
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<p>There are no options associated with the license command.</p>
<p><strong>Usage:</strong></p>
<p>Use the <code class="docutils literal notranslate"><span class="pre">license</span></code> command to display license information and expiration
date. Output at the command line (standard output) shows command name,
licensed status, and command release level.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#help"><span class="std std-ref">help</span></a>,
<a class="reference internal" href="#version"><span class="std std-ref">version</span></a></p>
</div>
</div>
<div class="section" id="help">
<h3>help<a class="headerlink" href="#help" title="Permalink to this headline">¶</a></h3>
<p><strong>Synopsis:</strong></p>
<p>The RTG help command provides online help for all RTG commands.</p>
<p><strong>Syntax:</strong></p>
<p>List all commands:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg help
</pre></div>
</div>
<p>Show usage syntax and flags for one command:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg help COMMAND
</pre></div>
</div>
<p><strong>Example:</strong></p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rtg help format
</pre></div>
</div>
<p><strong>Parameters:</strong></p>
<p>There are no options associated with the <code class="docutils literal notranslate"><span class="pre">help</span></code> command.</p>
<p><strong>Usage:</strong></p>
<p>Use the <code class="docutils literal notranslate"><span class="pre">help</span></code> command to view syntax and usage information for the main
<code class="docutils literal notranslate"><span class="pre">rtg</span></code> command as well as individual RTG commands.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#license"><span class="std std-ref">license</span></a>,
<a class="reference internal" href="#version"><span class="std std-ref">version</span></a></p>
</div>
</div>
</div>
</div>


            <div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
            <p class="logo"><a href="index.html">
              <img class="logo" src="_static/html_logo.png" alt="Logo"/>
            </a></p>
  <h3><a href="index.html">Table of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">RTG Command Reference</a><ul>
<li><a class="reference internal" href="#command-line-interface-cli">Command line interface (CLI)</a></li>
<li><a class="reference internal" href="#rtg-command-syntax">RTG command syntax</a></li>
<li><a class="reference internal" href="#data-formatting-commands">Data Formatting Commands</a><ul>
<li><a class="reference internal" href="#format">format</a></li>
<li><a class="reference internal" href="#sdf2fasta">sdf2fasta</a></li>
<li><a class="reference internal" href="#sdf2fastq">sdf2fastq</a></li>
<li><a class="reference internal" href="#sdf2sam">sdf2sam</a></li>
<li><a class="reference internal" href="#fastqtrim">fastqtrim</a></li>
<li><a class="reference internal" href="#petrim">petrim</a></li>
</ul>
</li>
<li><a class="reference internal" href="#simulation-commands">Simulation Commands</a><ul>
<li><a class="reference internal" href="#genomesim">genomesim</a></li>
<li><a class="reference internal" href="#cgsim">cgsim</a></li>
<li><a class="reference internal" href="#readsim">readsim</a></li>
<li><a class="reference internal" href="#popsim">popsim</a></li>
<li><a class="reference internal" href="#samplesim">samplesim</a></li>
<li><a class="reference internal" href="#denovosim">denovosim</a></li>
<li><a class="reference internal" href="#childsim">childsim</a></li>
<li><a class="reference internal" href="#pedsamplesim">pedsamplesim</a></li>
<li><a class="reference internal" href="#samplereplay">samplereplay</a></li>
</ul>
</li>
<li><a class="reference internal" href="#utility-commands">Utility Commands</a><ul>
<li><a class="reference internal" href="#bgzip">bgzip</a></li>
<li><a class="reference internal" href="#index">index</a></li>
<li><a class="reference internal" href="#extract">extract</a></li>
<li><a class="reference internal" href="#aview">aview</a></li>
<li><a class="reference internal" href="#sdfstats">sdfstats</a></li>
<li><a class="reference internal" href="#sdfsubset">sdfsubset</a></li>
<li><a class="reference internal" href="#sdfsubseq">sdfsubseq</a></li>
<li><a class="reference internal" href="#mendelian">mendelian</a></li>
<li><a class="reference internal" href="#vcfannotate">vcfannotate</a></li>
<li><a class="reference internal" href="#vcfdecompose">vcfdecompose</a></li>
<li><a class="reference internal" href="#vcfeval">vcfeval</a></li>
<li><a class="reference internal" href="#vcffilter">vcffilter</a></li>
<li><a class="reference internal" href="#vcfmerge">vcfmerge</a></li>
<li><a class="reference internal" href="#vcfsplit">vcfsplit</a></li>
<li><a class="reference internal" href="#vcfstats">vcfstats</a></li>
<li><a class="reference internal" href="#vcfsubset">vcfsubset</a></li>
<li><a class="reference internal" href="#vcf2rocplot">vcf2rocplot</a></li>
<li><a class="reference internal" href="#svdecompose">svdecompose</a></li>
<li><a class="reference internal" href="#bndeval">bndeval</a></li>
<li><a class="reference internal" href="#pedfilter">pedfilter</a></li>
<li><a class="reference internal" href="#pedstats">pedstats</a></li>
<li><a class="reference internal" href="#rocplot">rocplot</a></li>
<li><a class="reference internal" href="#version">version</a></li>
<li><a class="reference internal" href="#license">license</a></li>
<li><a class="reference internal" href="#help">help</a></li>
</ul>
</li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="overview.html"
                        title="previous chapter">Overview</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="product_usage.html"
                        title="next chapter">RTG product usage - baseline progressions</a></p>
  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="_sources/rtg_command_reference.rst.txt"
            rel="nofollow">Show Source</a></li>
    </ul>
   </div>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="product_usage.html" title="RTG product usage - baseline progressions"
             >next</a> |</li>
        <li class="right" >
          <a href="overview.html" title="Overview"
             >previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="index.html">RTG Tools Operations Manual v3.12</a> &#187;</li>
        <li class="nav-item nav-item-this"><a href="">RTG Command Reference</a></li> 
      </ul>
    </div>
    <div class="footer" role="contentinfo">
        &#169; Copyright 2017, Real Time Genomics.
      Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.1.2.
    </div>
  </body>
</html>